# 构建配置

<cite>
**本文引用的文件**
- [vite.config.ts](file://my-uniapp-vue3/vite.config.ts)
- [package.json](file://my-uniapp-vue3/package.json)
- [tsconfig.json](file://my-uniapp-vue3/tsconfig.json)
- [main.ts](file://my-uniapp-vue3/src/main.ts)
- [env.d.ts](file://my-uniapp-vue3/src/env.d.ts)
- [manifest.json](file://my-uniapp-vue3/src/manifest.json)
- [pages.json](file://my-uniapp-vue3/src/pages.json)
- [DEPLOY.md](file://DEPLOY.md)
- [deploy.sh](file://deploy.sh)
- [deploy-prod.sh](file://deploy-prod.sh)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向“AI有声书生成平台”的前端构建与部署，聚焦于 Vite 构建工具在 uni-app 场景下的配置与优化、多平台编译与打包策略、开发与生产环境差异、热更新机制、代码分割与资源压缩、CDN 集成思路，以及部署前准备与运维要点。内容基于仓库中实际存在的配置文件与脚本进行梳理与说明。

## 项目结构
前端工程位于 my-uniapp-vue3 目录，采用 uni-app + Vue3 + Vite 的组合，通过 @dcloudio/vite-plugin-uni 提供多端编译支持；后端工程位于 server 目录，使用 Node.js + Express + Prisma；部署脚本位于根目录，包含本地构建与远程部署流程。

```mermaid
graph TB
subgraph "前端(uni-app)"
VCFG["vite.config.ts"]
PKG["package.json"]
TS["tsconfig.json"]
MAIN["src/main.ts"]
ENV["src/env.d.ts"]
MANI["src/manifest.json"]
PAGES["src/pages.json"]
end
subgraph "后端(Node.js)"
SAPP["server/src/app.ts"]
SCONF["server/src/config/index.ts"]
SDEP["server/package.json"]
end
subgraph "部署脚本"
DSH["deploy.sh"]
DPROM["deploy-prod.sh"]
DMD["DEPLOY.md"]
end
VCFG --> PKG
PKG --> MAIN
MAIN --> MANI
MAIN --> PAGES
VCFG -. 代理/服务 .-> SAPP
DSH --> VCFG
DPROM --> VCFG
DMD --> DSH
DMD --> DPROM
```

图表来源
- [vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)
- [package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [tsconfig.json:1-14](file://my-uniapp-vue3/tsconfig.json#L1-L14)
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)
- [manifest.json:1-52](file://my-uniapp-vue3/src/manifest.json#L1-L52)
- [pages.json:1-211](file://my-uniapp-vue3/src/pages.json#L1-L211)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)

章节来源
- [vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)
- [package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [tsconfig.json:1-14](file://my-uniapp-vue3/tsconfig.json#L1-L14)
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)
- [manifest.json:1-52](file://my-uniapp-vue3/src/manifest.json#L1-L52)
- [pages.json:1-211](file://my-uniapp-vue3/src/pages.json#L1-L211)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)

## 核心组件
- Vite 构建配置：定义插件、开发服务器代理、跨域与本地联调。
- uni-app 编译：通过 @dcloudio/vite-plugin-uni 实现 H5、小程序、快应用等多端输出。
- TypeScript 配置：启用 sourceMap、路径别名、类型声明。
- 应用入口：创建 SSR App、初始化 Pinia、条件性引入 vConsole。
- Manifest/Pages：页面路由、TabBar、模块与权限声明。
- 部署脚本：本地构建、远程同步、Nginx 配置、PM2 启动与备份。

章节来源
- [vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)
- [package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [tsconfig.json:1-14](file://my-uniapp-vue3/tsconfig.json#L1-L14)
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)
- [manifest.json:1-52](file://my-uniapp-vue3/src/manifest.json#L1-L52)
- [pages.json:1-211](file://my-uniapp-vue3/src/pages.json#L1-L211)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)

## 架构总览
下图展示从开发到生产的整体流程：本地 Vite 启动与代理，uni-app 多端编译，本地/远程构建产物，Nginx 反向代理与静态资源缓存，PM2 管理后端服务。

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Vite as "Vite 开发服务器"
participant Uni as "@dcloudio/vite-plugin-uni"
participant Build as "构建产物(dist)"
participant Nginx as "Nginx"
participant PM2 as "PM2"
participant API as "后端服务"
Dev->>Vite : 启动开发服务器
Vite->>Uni : 触发多端编译
Uni-->>Build : 输出 H5/小程序/快应用等
Dev->>Nginx : 访问前端静态页(反向代理)
Nginx->>API : 将 /api 前缀转发至后端
PM2->>API : 管理进程与自动重启
```

图表来源
- [vite.config.ts:7-22](file://my-uniapp-vue3/vite.config.ts#L7-L22)
- [package.json:4-37](file://my-uniapp-vue3/package.json#L4-L37)
- [DEPLOY.md:61-116](file://DEPLOY.md#L61-L116)
- [deploy.sh:178-201](file://deploy.sh#L178-L201)

## 详细组件分析

### Vite 构建配置与插件
- 插件：使用 @dcloudio/vite-plugin-uni，负责 uni-app 多端编译。
- 开发服务器：配置 /api、/uploads、/videos 三类请求代理到本地后端，便于前后端联调。
- 适用场景：本地开发时，避免 CORS 与跨域问题，统一走本地 3000 端口。

```mermaid
flowchart TD
Start(["Vite 启动"]) --> Proxy["配置代理规则<br/>/api -> http://localhost:3000<br/>/uploads -> http://localhost:3000<br/>/videos -> http://localhost:3000"]
Proxy --> DevServe["启动开发服务器"]
DevServe --> Build["触发 uni-app 编译"]
Build --> Dist["生成多端产物"]
Dist --> End(["联调/预览"])
```

图表来源
- [vite.config.ts:5-22](file://my-uniapp-vue3/vite.config.ts#L5-L22)

章节来源
- [vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)

### uni-app 编译与多平台打包
- 脚本命令：通过 uni 与 uni build 支持 H5、微信小程序、支付宝小程序、百度小程序、今日头条、快手、Harmony、小红书、快应用 Webview 等平台。
- 平台差异：不同平台在 manifest.json 中声明模块、权限、SDK 配置；pages.json 统一页面与 TabBar 配置。
- 构建产物：H5 默认输出至 dist/h5；其他平台输出至对应目录（由 uni-app 插件决定）。

```mermaid
flowchart TD
CMD["执行构建脚本<br/>uni / uni build"] --> UniPlugin["@dcloudio/vite-plugin-uni"]
UniPlugin --> H5["H5 产物"]
UniPlugin --> MP["小程序/快应用 产物"]
H5 --> Dist["dist/h5"]
MP --> Out["各平台输出目录"]
```

图表来源
- [package.json:4-37](file://my-uniapp-vue3/package.json#L4-L37)
- [manifest.json:8-39](file://my-uniapp-vue3/src/manifest.json#L8-L39)
- [pages.json:1-211](file://my-uniapp-vue3/src/pages.json#L1-L211)

章节来源
- [package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [manifest.json:1-52](file://my-uniapp-vue3/src/manifest.json#L1-L52)
- [pages.json:1-211](file://my-uniapp-vue3/src/pages.json#L1-L211)

### TypeScript 与类型声明
- tsconfig：启用 sourceMap，配置路径别名 @/*，指定 lib 与类型声明。
- env.d.ts：为 .vue 文件提供类型支持，确保 IDE 正确识别单文件组件。

```mermaid
graph LR
TS["tsconfig.json"] --> Alias["@/* 别名"]
TS --> Lib["lib: esnext, dom"]
TS --> Src["include: *.ts, *.vue"]
ENV["src/env.d.ts"] --> VueType[".vue 类型声明"]
```

图表来源
- [tsconfig.json:1-14](file://my-uniapp-vue3/tsconfig.json#L1-L14)
- [env.d.ts:1-9](file://my-uniapp-vue3/src/env.d.ts#L1-L9)

章节来源
- [tsconfig.json:1-14](file://my-uniapp-vue3/tsconfig.json#L1-L14)
- [env.d.ts:1-9](file://my-uniapp-vue3/src/env.d.ts#L1-L9)

### 应用入口与运行时初始化
- 入口函数 createApp：创建 SSR App、注册 Pinia、初始化用户状态。
- 条件引入 vConsole：H5 环境下可按需启用移动端调试面板。

```mermaid
sequenceDiagram
participant Entry as "入口(main.ts)"
participant App as "SSR App"
participant Store as "Pinia"
participant User as "用户状态"
Entry->>App : createSSRApp(App)
Entry->>Store : createPinia()
Entry->>User : useUserStore().initUser()
Note over Entry,App : H5 下可选择性启用 vConsole
```

图表来源
- [main.ts:10-31](file://my-uniapp-vue3/src/main.ts#L10-L31)

章节来源
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)

### 页面与清单配置
- pages.json：集中声明页面路径、导航样式、TabBar 列表与全局样式。
- manifest.json：声明 app 名称、版本、plus 模块与权限、小程序 SDK 配置等。

```mermaid
graph TB
PAGES["pages.json"] --> Pages["页面列表/导航/TabBar"]
MANI["manifest.json"] --> AppInfo["应用信息/版本"]
MANI --> Modules["模块/权限/SDK"]
PAGES --> UI["页面样式/交互"]
MANI --> Runtime["运行时配置"]
```

图表来源
- [pages.json:1-211](file://my-uniapp-vue3/src/pages.json#L1-L211)
- [manifest.json:1-52](file://my-uniapp-vue3/src/manifest.json#L1-L52)

章节来源
- [pages.json:1-211](file://my-uniapp-vue3/src/pages.json#L1-L211)
- [manifest.json:1-52](file://my-uniapp-vue3/src/manifest.json#L1-L52)

### 开发环境配置与热更新
- 代理配置：将 /api、/uploads、/videos 请求代理到本地后端，便于联调。
- HMR：Vite 默认提供模块热替换，配合 uni-app 插件实现多端热更新体验。
- 调试：H5 环境可按需启用 vConsole 进行移动端调试。

章节来源
- [vite.config.ts:7-22](file://my-uniapp-vue3/vite.config.ts#L7-L22)
- [main.ts:20-25](file://my-uniapp-vue3/src/main.ts#L20-L25)

### 生产环境优化与部署准备
- 本地构建：分别对后端与前端执行构建，生成 dist 与 dist/h5。
- 远程部署：通过 scp/sftp 将 dist 与 server 发布到服务器，备份旧版本，安装生产依赖，生成 Prisma 客户端。
- Nginx：配置前端静态站点与后端 API 反代，设置缓存头与安全头。
- PM2：以守护进程方式启动后端服务，设置开机自启与日志管理。

```mermaid
flowchart TD
LBuild["本地构建<br/>后端: npm run build<br/>前端: uni build(h5)"] --> Sync["同步到服务器"]
Sync --> Backup["备份旧版本"]
Backup --> Install["安装生产依赖/生成 Prisma 客户端"]
Install --> Nginx["配置 Nginx 反代与缓存"]
Nginx --> PM2["PM2 启动后端服务"]
PM2 --> Verify["健康检查与日志查看"]
```

图表来源
- [deploy.sh:22-31](file://deploy.sh#L22-L31)
- [deploy.sh:54-89](file://deploy.sh#L54-L89)
- [DEPLOY.md:61-116](file://DEPLOY.md#L61-L116)
- [deploy-prod.sh:137-164](file://deploy-prod.sh#L137-L164)

章节来源
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)

### 代码分割策略
- uni-app 多端编译：由 @dcloudio/vite-plugin-uni 控制分包与按需加载，结合 pages.json 的页面拆分实现天然的代码分割。
- 建议实践：将业务页面按模块拆分，减少首屏体积；对第三方库进行外部化或动态导入，降低主包大小。

章节来源
- [package.json:52-62](file://my-uniapp-vue3/package.json#L52-L62)
- [pages.json:1-211](file://my-uniapp-vue3/src/pages.json#L1-L211)

### 资源压缩与缓存
- 前端静态资源：Nginx 对 JS/CSS/PNG/JPG/GIF/ICO/WOFF/WOFF2/TTF/EOT 等设置长缓存与 immutable。
- 后端 API：通过反向代理将 /api 前缀转发至后端，避免静态资源混淆。
- 建议：开启 Gzip/Brotli 压缩与 HTTP/2，合理设置 Cache-Control 与 ETag。

章节来源
- [DEPLOY.md:97-101](file://DEPLOY.md#L97-L101)
- [vite.config.ts:9-20](file://my-uniapp-vue3/vite.config.ts#L9-L20)

### CDN 集成方案
- 方案思路：将静态资源（JS/CSS/媒体）托管至 CDN，回源至 Nginx；对版本化文件设置长缓存，非版本化文件短缓存或不缓存。
- 注意事项：确保 CDN 与源站的缓存头一致，避免跨域与证书问题；对 /api 前缀保持直连后端。

章节来源
- [DEPLOY.md:90-101](file://DEPLOY.md#L90-L101)

## 依赖关系分析
- 构建链路：package.json 的 scripts 通过 uni/uni build 调用 @dcloudio/vite-plugin-uni，后者读取 vite.config.ts 的插件与代理配置。
- 运行链路：Nginx 将 /api 前缀代理至后端，PM2 管理 Node.js 进程；前端通过 dist/h5 提供静态页面。

```mermaid
graph LR
Scripts["package.json scripts"] --> UniPlugin["@dcloudio/vite-plugin-uni"]
UniPlugin --> ViteCfg["vite.config.ts"]
ViteCfg --> Dist["dist/h5"]
Dist --> Nginx["Nginx 静态站点"]
Nginx --> API["/api 反代后端"]
API --> PM2["PM2 管理后端"]
```

图表来源
- [package.json:4-37](file://my-uniapp-vue3/package.json#L4-L37)
- [vite.config.ts:5-6](file://my-uniapp-vue3/vite.config.ts#L5-L6)
- [DEPLOY.md:64-81](file://DEPLOY.md#L64-L81)

章节来源
- [package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)
- [DEPLOY.md:1-251](file://DEPLOY.md#L1-L251)

## 性能考虑
- 构建性能：优先使用 SSD、合理配置 node_modules 缓存；在 CI 中复用依赖缓存。
- 传输性能：开启 gzip/br 压缩与 HTTP/2；CDN 回源使用就近节点。
- 运行性能：合理拆分页面与懒加载；对大体积第三方库进行动态导入；利用浏览器缓存与 ETag。

## 故障排查指南
- 后端无法启动
  - 检查端口占用与环境变量，查看 PM2 日志。
- 前端无法访问
  - 检查 Nginx 配置与站点权限，确认 dist 目录存在。
- 数据库连接失败
  - 检查数据库服务状态与连接配置文件。

章节来源
- [DEPLOY.md:199-214](file://DEPLOY.md#L199-L214)

## 结论
本项目采用 Vite + uni-app 的现代化前端构建体系，结合 Nginx 与 PM2 的稳定后端部署，形成从开发到生产的完整闭环。通过代理联调、多端编译、静态资源缓存与进程守护，能够满足 AI 有声书平台在多平台与高并发场景下的交付需求。后续可在 CDN 集成、代码分割与缓存策略上进一步优化。

## 附录
- 常用命令
  - 开发：H5 开发、小程序开发、SSR 开发等。
  - 构建：H5 构建、SSR 构建、各平台构建。
- 部署脚本
  - deploy.sh：本地构建、远程同步、Nginx 配置、PM2 启动。
  - deploy-prod.sh：生产环境一键部署脚本，含 Node.js 检测与备份。

章节来源
- [package.json:4-37](file://my-uniapp-vue3/package.json#L4-L37)
- [deploy.sh:1-209](file://deploy.sh#L1-L209)
- [deploy-prod.sh:1-171](file://deploy-prod.sh#L1-L171)