构建与预渲染

本页介绍项目的构建与预渲染流程：npm 脚本一览、构建的两个阶段、新增路由后的处理，以及部署前的预览验收与故障排查。

npm 脚本一览

命令	作用
npm run dev	启动开发服务器（热更新）
npm run build	构建生产版本 = vite build + 预渲染
npm run preview	本地预览 dist/ 产物
npm run lint	ESLint 检查全部源码

package.json 中的 build 脚本：

"build": "vite build && node scripts/prerender.js"

构建流程详解

第 1 步：vite build

构建产物输出到 dist/。构建期间，vite.config.js 中的两个自定义插件会生效：

插件	作用
injectThemeVariables	读取 src/config/theme.config.js，把配色 / 字体 / 特效参数中的标量值拍平成 CSS 变量，注入 src/index.css 的 @tailwind 之前
injectFontDisplaySwap	为 LXGW 字体 CSS 注入 font-display: swap，避免字体下载期间文字不可见

此外：

• public/ 目录（图片、音乐、图标、robots.txt、sitemap.xml、_redirects）原样拷贝到 dist/
• 依赖自动分包，路由级懒加载的 /contributors 单独成 chunk

第 2 步：node scripts/prerender.js —— 预渲染

这是一个 Node 脚本（http 起服务 + Playwright 无头浏览器，依赖已含在 devDependencies 的 @playwright/test 中，浏览器需单独安装一次 npx playwright install chromium）：

1. 在 4321 端口起一个带 SPA 回退的静态服务器
2. 依次打开路由 / 和 /contributors，等待网络空闲 + #root 挂载（即 React 渲染完成）
3. 把渲染后的完整 HTML 写回：
   • / → dist/index.html
   • /contributors → dist/contributors/index.html

为什么要预渲染？

React 是客户端渲染（CSR），搜索引擎抓到的初始 HTML 是空 <div id="root">。预渲染后：

• 每个路由都有内容完整的静态 HTML → SEO 大幅提升
• 分享链接（微信 / QQ / Discord 读取 og 标签）能抓到正确内容
• dist/contributors/index.html 静态存在 → 深链直接访问 / 刷新不依赖回退规则

新增路由后的处理

在 scripts/prerender.js 顶部的 routes 数组中添加新路径：

const routes = ['/', '/contributors'];

若遗漏，该页面的 SEO 会退化为空壳，且部分托管平台上深链刷新可能返回 404。

预览产物

npm run preview

该命令由 Vite 启动本地服务预览 dist/，用于部署前的最终验收：

• [ ] 首页与 /contributors 内容完整
• [ ] 直接刷新 /contributors 正常（不 404）
• [ ] 浅色 / 深色切换正常
• [ ] 音乐可播放、图片完整
• [ ] 「查看页面源代码」能看到真实内容（预渲染生效）

故障排查

问题	原因与解决
预渲染失败：Executable doesn't exist	未安装浏览器：npx playwright install chromium
预渲染的 HTML 是空壳	构建产物路径不对，或页面在 networkidle 前有阻塞请求；检查 #root 是否正常挂载
想跳过预渲染	直接运行 npx vite build（会失去 SEO 优势，不建议作为常规做法）
构建通过但样式全是默认值	theme.config.js 语法错误导致 Vite 插件读取失败；检查 dev 模式下是否有报错