签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,82 @@
+# 9.3 环境与构建配置
+
+:::tip 概述
+前端构建基于 Vite 多环境模式：dev/test/uat/prod 四套构建命令 + 环境变量文件。开发环境经 Vite proxy 代理 /api 到后端；生产构建产物交 Nginx 托管。
+:::
+
+## 构建命令（package.json）
+
+```sh
+pnpm dev            # 开发服务器（vite）
+pnpm build          # production 模式构建 + postBuild 后处理
+pnpm build:prod     # --mode production
+pnpm build:uat      # --mode uat
+pnpm build:test     # --mode test
+pnpm build:dev      # --mode dev
+pnpm preview        # 构建 + vite preview 本地预览
+pnpm type:check     # vue-tsc --noEmit --skipLibCheck
+```
+
+构建产物经 `build/script/postBuild.ts` 后处理输出 `dist/`。
+
+## Vite 配置要点（vite.config.ts）
+
+```text
+关键配置：
+  * Vite 端口与 host
+  * proxy：/api → http://127.0.0.1:8000（开发代理，同源化）
+  * 别名 @ → src
+  * unplugin-auto-import / 组件自动注册等工程插件
+```
+
+开发代理让前端"同源"访问后端——dev 环境无 CORS 问题；生产建议 Nginx 同域反代 /api。
+
+## 环境变量
+
+```text
+.env.development / .env.test / .env.uat / .env.production
+
+常用键（以项目实际文件为准）：
+  VITE_PORT                  开发端口（默认 8001）
+  VITE_PUBLIC_PATH           部署公网路径（子路径部署时配置）
+  VITE_GLOB_API_URL          API 地址（baseURL，一般留空，由前缀拼接）
+  VITE_GLOB_API_URL_PREFIX   API 版本前缀（/api，与后端公开路径规则配套）
+  VITE_GLOB_UPLOAD_URL       上传接口地址
+  VITE_GLOB_IMG_URL          图片服务地址（对应后端 file.domainUrl）
+```
+
+代码经 `useGlobSetting()`（hooks/setting）读取环境变量，统一收敛不散落。
+
+## baseURL 与代理的配合
+
+```text
+开发：axios baseURL = /api → Vite proxy 转发 :8000
+生产：axios baseURL = /api → Nginx location /api/ 反代后端
+
+注意：接口 url 在 api 模块里不写 /api 前缀（如 '/user/page'），
+     baseURL 已含 /api；后端 gmeta path 是 /api/user/page——两层拼接对齐。
+无 /v1 版本段：不要拼 /v1。
+```
+
+## lint 与质量工具
+
+| 工具 | 命令 | 作用 |
+|------|------|------|
+| ESLint | pnpm lint:eslint | TS/Vue 代码检查修复 |
+| Prettier | pnpm lint:prettier | 格式化 |
+| Stylelint | pnpm lint:stylelint | 样式检查 |
+| commitlint | （husky 提交钩子） | 提交信息规范 |
+| vue-tsc | pnpm type:check | 类型检查 |
+
+## 生产部署形态
+
+```text
+Nginx：
+  location /        → 静态资源 dist/
+  location /api/    → 反代后端 :8000
+  location /upload/ → 反代后端（或直挂文件服务/CDN）
+  try_files $uri $uri/ /index.html   （SPA 路由回退）
+
+子路径部署：VITE_PUBLIC_PATH=/admin/ + Nginx location /admin/
+详见 11.5 前端部署
+```