liumangmang
101 lines
3.5 KiB
Markdown
101 lines
3.5 KiB
Markdown
# 前端构建说明
|
||
|
||
## 目录职责
|
||
|
||
| 目录 | 说明 |
|
||
|------|------|
|
||
| `frontend-vue/` | 前端源码（Vue 3 + Vite） |
|
||
| `src/main/resources/static/v2/` | **前端构建产物**，由 Vite 生成，不要手工修改 |
|
||
|
||
> ⚠️ `static/v2/` 是自动生成目录，请勿直接手工编辑其中的文件，
|
||
> 应始终通过构建前端源码来更新。
|
||
|
||
---
|
||
|
||
## 本地开发
|
||
|
||
启动前端开发服务器（热重载，代理到后端 :8080）：
|
||
|
||
```bash
|
||
cd frontend-vue
|
||
npm install # 首次或依赖变更时
|
||
npm run dev # 启动 Vite dev server，访问 http://localhost:5173/v2/
|
||
```
|
||
|
||
---
|
||
|
||
## Maven 打包（含前端构建）
|
||
|
||
项目使用 `frontend-maven-plugin` 绑定在 **`prepare-package`** 阶段，
|
||
只有 `mvn package`（及后续阶段）才会触发前端构建：
|
||
|
||
| 命令 | 前端构建 |
|
||
|------|---------|
|
||
| `mvn compile` | ❌ 不触发 |
|
||
| `mvn test` | ❌ 不触发 |
|
||
| `mvn package` | ✅ 自动执行 `install-node（v20 LTS） → npm ci → npm run build` |
|
||
```bash
|
||
# 完整打包（含前端构建，首次默认自动下载 Node）
|
||
mvn clean package -DskipTests
|
||
|
||
# 如果 nodejs.org 下载极慢或报错（如 Premature end of Content-Length），可指定国内镜像源：
|
||
mvn clean package -DskipTests -Dnode.download.root=https://npmmirror.com/mirrors/node/
|
||
|
||
# 跳过前端构建（前提：static/v2/ 中已存有最新的构建产物）
|
||
mvn clean package -DskipTests -Dskip.frontend.build=true
|
||
```
|
||
|
||
### 离线与缓存方案 (CI / 弱网环境)
|
||
|
||
由于默认全量打包依赖外网 Node.js 下载，当本地/CI环境无法直接访问外网或网络极其不稳定时，建议采用以下优化方案：
|
||
|
||
1. **手动预缓存 Node.js 包（最稳妥的离线打包方案）**
|
||
您可以直接手动下载对应平台的 Node 压缩包，并放置到本地 Maven 缓存目录中。以 Linux x64 平台为例：
|
||
- 下载对应版本的 Node 包：[node-v20.11.0-linux-x64.tar.gz](https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.gz)
|
||
- 保存到本地 Maven 仓库缓存路径下：
|
||
`~/.m2/repository/com/github/eirslett/node/20.11.0/node-20.11.0-linux-x64.tar.gz`
|
||
- 再次运行 `mvn package` 时，插件检测到该本地缓存文件存在，将**直接读取该文件进行解压**，不会发起任何外网下载请求。
|
||
|
||
2. **切换镜像源**
|
||
如果网络通畅但仅访问官方 nodejs.org 受限，可以使用 `-Dnode.download.root` 参数切换至其他镜像源：
|
||
- 阿里云镜像：`-Dnode.download.root=https://npmmirror.com/mirrors/node/`
|
||
- 华为云镜像：`-Dnode.download.root=https://mirrors.huaweicloud.com/nodejs/`
|
||
|
||
3. **跳过前端构建**
|
||
如果仅变更后端 Java 代码，不需要重新编译前端，可直接通过 `-Dskip.frontend.build=true` 跳过前端：
|
||
`mvn clean package -DskipTests -Dskip.frontend.build=true`
|
||
|
||
---
|
||
|
||
## Docker 构建（推荐生产方式）
|
||
|
||
```bash
|
||
make up
|
||
```
|
||
|
||
Dockerfile 使用多阶段构建：
|
||
1. Stage 1（`frontend-builder`）：`node:22-alpine` 执行 `npm ci && npm run build`
|
||
2. Stage 2（`builder`）：Maven 将前端产物 COPY 进来并打包 jar
|
||
3. Stage 3（`runner`）：最小 JRE 运行
|
||
|
||
---
|
||
|
||
## 首次配置 API Key 说明
|
||
|
||
服务启动后，如果未配置 API Key，`/api/settings` 返回：
|
||
|
||
```json
|
||
{
|
||
"apiKeyConfigured": false,
|
||
"apiKeySource": "none"
|
||
}
|
||
```
|
||
|
||
这是**正常状态**，请前往设置页配置 DeepSeek API Key 或 OpenAI 兼容 API Key。
|
||
|
||
也可通过环境变量配置 DeepSeek API Key：
|
||
|
||
```bash
|
||
export DEEPSEEK_API_KEY=sk-xxxxxxxx
|
||
```
|