audio_codebuddy/.qoder/repowiki/zh/content/前端架构/构建配置.md

构建配置

本文引用的文件

• vite.config.ts
• package.json
• tsconfig.json
• main.ts
• env.d.ts
• manifest.json
• pages.json
• DEPLOY.md
• deploy.sh
• deploy-prod.sh

目录

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；部署脚本位于根目录，包含本地构建与远程部署流程。

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
• package.json:1-65
• tsconfig.json:1-14
• main.ts:1-32
• manifest.json:1-52
• pages.json:1-211
• deploy.sh:1-209
• deploy-prod.sh:1-171
• DEPLOY.md:1-251

章节来源

• vite.config.ts:1-24
• package.json:1-65
• tsconfig.json:1-14
• main.ts:1-32
• manifest.json:1-52
• pages.json:1-211
• deploy.sh:1-209
• deploy-prod.sh:1-171
• DEPLOY.md:1-251

核心组件

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

章节来源

• vite.config.ts:1-24
• package.json:1-65
• tsconfig.json:1-14
• main.ts:1-32
• manifest.json:1-52
• pages.json:1-211
• deploy.sh:1-209
• deploy-prod.sh:1-171
• DEPLOY.md:1-251

架构总览

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

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
• package.json:4-37
• DEPLOY.md:61-116
• deploy.sh:178-201

详细组件分析

Vite 构建配置与插件

• 插件：使用 @dcloudio/vite-plugin-uni，负责 uni-app 多端编译。
• 开发服务器：配置 /api、/uploads、/videos 三类请求代理到本地后端，便于前后端联调。

• 适用场景：本地开发时，避免 CORS 与跨域问题，统一走本地 3000 端口。

  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

章节来源

• vite.config.ts:1-24

uni-app 编译与多平台打包

• 脚本命令：通过 uni 与 uni build 支持 H5、微信小程序、支付宝小程序、百度小程序、今日头条、快手、Harmony、小红书、快应用 Webview 等平台。
• 平台差异：不同平台在 manifest.json 中声明模块、权限、SDK 配置；pages.json 统一页面与 TabBar 配置。

• 构建产物：H5 默认输出至 dist/h5；其他平台输出至对应目录（由 uni-app 插件决定）。

  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
• manifest.json:8-39
• pages.json:1-211

章节来源

• package.json:1-65
• manifest.json:1-52
• pages.json:1-211

TypeScript 与类型声明

• tsconfig：启用 sourceMap，配置路径别名 @/*，指定 lib 与类型声明。

• env.d.ts：为 .vue 文件提供类型支持，确保 IDE 正确识别单文件组件。

  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
• env.d.ts:1-9

章节来源

• tsconfig.json:1-14
• env.d.ts:1-9

应用入口与运行时初始化

• 入口函数 createApp：创建 SSR App、注册 Pinia、初始化用户状态。

• 条件引入 vConsole：H5 环境下可按需启用移动端调试面板。

  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

章节来源

• main.ts:1-32

页面与清单配置

• pages.json：集中声明页面路径、导航样式、TabBar 列表与全局样式。

• manifest.json：声明 app 名称、版本、plus 模块与权限、小程序 SDK 配置等。

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

图表来源

• pages.json:1-211
• manifest.json:1-52

章节来源

• pages.json:1-211
• manifest.json:1-52

开发环境配置与热更新

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

章节来源

• vite.config.ts:7-22
• main.ts:20-25

生产环境优化与部署准备

• 本地构建：分别对后端与前端执行构建，生成 dist 与 dist/h5。
• 远程部署：通过 scp/sftp 将 dist 与 server 发布到服务器，备份旧版本，安装生产依赖，生成 Prisma 客户端。
• Nginx：配置前端静态站点与后端 API 反代，设置缓存头与安全头。

• PM2：以守护进程方式启动后端服务，设置开机自启与日志管理。

  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
• deploy.sh:54-89
• DEPLOY.md:61-116
• deploy-prod.sh:137-164

章节来源

• deploy.sh:1-209
• deploy-prod.sh:1-171
• DEPLOY.md:1-251

代码分割策略

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

章节来源

• package.json:52-62
• pages.json:1-211

资源压缩与缓存

• 前端静态资源：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
• vite.config.ts:9-20

CDN 集成方案

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

章节来源

• DEPLOY.md:90-101

依赖关系分析

• 构建链路：package.json 的 scripts 通过 uni/uni build 调用 @dcloudio/vite-plugin-uni，后者读取 vite.config.ts 的插件与代理配置。

• 运行链路：Nginx 将 /api 前缀代理至后端，PM2 管理 Node.js 进程；前端通过 dist/h5 提供静态页面。

  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
• vite.config.ts:5-6
• DEPLOY.md:64-81

章节来源

• package.json:1-65
• vite.config.ts:1-24
• DEPLOY.md:1-251

性能考虑

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

故障排查指南

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

章节来源

• DEPLOY.md:199-214

结论

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

附录

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

章节来源

• package.json:4-37
• deploy.sh:1-209
• deploy-prod.sh:1-171