静态博客的构建不只是“把 Markdown 转成 HTML”。一个可靠的构建流程需要在部署前捕获尽可能多的问题：格式错误、类型不匹配、断链、可访问性问题。本文记录这个站点的构建验证流程。
验证层次
构建验证分为五个层次，从最快到最慢依次执行：
1. 格式检查（Prettier）
最快的检查，确保所有文件的格式一致：
npm run format:checkPrettier 检查的不是“代码是否正确”，而是“代码是否好看”。统一的格式减少代码审查时的噪音，让审阅者专注于逻辑问题。
2. 代码质量（ESLint）
检查 TypeScript 和 Astro 文件的代码质量：
npm run lintESLint 捕获的问题包括：
- 未使用的变量和导入。
- 潜在的类型错误。
- 不安全的函数调用。
- 代码风格问题（与 Prettier 互补）。
3. 类型检查（Astro Check）
验证所有组件和页面的类型安全：
npm run typecheckTypeScript 在构建时捕获的错误包括：
- 组件 Props 类型不匹配。
- 内容 Schema 与实际 frontmatter 不一致。
- API 调用的参数类型错误。
- 导入路径错误。
4. 单元测试（Vitest）
验证核心逻辑的正确性：
npm test单元测试覆盖的模块包括：
- 内容过滤逻辑（
getPublicContent）。 - 阅读时间估算（
estimateReadingMinutes）。 - Reader 数据适配（
adaptGReaderPayload）。 - 主题切换逻辑。
- CMS 配置生成。
5. 构建与集成检查
构建完成后执行的检查：
npm run build构建流程包含：
- Astro 构建：生成所有静态页面。
- Pagefind 索引：为搜索功能生成索引。
- 前端资源检查：验证所有引用的资源文件存在。
- Lunar 资源检查：验证 3D 场景的资源预算。
- 链接检查：使用 linkinator 检测断链。
完整验证流程
npm run verify 命令按顺序执行所有检查：
npm run format:check && \
npm run lint && \
npm run typecheck && \
npm run test && \
npm run build && \
npm run check:frontend-assets && \
npm run check:lunar-assets && \
npm run check:links && \
npm run test:e2e任何一步失败都会中断流程，确保问题不会被部署到生产环境。
构建产物检查
构建完成后，有几个专门的检查确保产物的完整性：
前端资源检查
验证所有引用的 CSS、JS 和图片文件都存在于构建产物中。避免“构建成功但页面加载时缺少资源”的问题。
Lunar 资源检查
验证 3D 月球场景的资源（模型、纹理、着色器）在预算范围内。3D 资源容易意外膨胀，这个检查防止构建产物过大。
链接检查
使用 linkinator 递归检查所有页面中的链接：
node -e "require('linkinator').linkinate('dist', {recurse: true, skip: /^https://chumanic[.]com/})"跳过指向自身的链接（避免检查正在构建的本地服务器），其他所有链接都需要返回 200 状态码。
端到端测试
在构建产物上运行 Playwright 端到端测试：
npm run test:e2e端到端测试验证：
- 页面可以正常加载。
- 导航链接可以正常跳转。
- 搜索功能可以正常工作。
- 主题切换可以正常生效。
CI/CD 集成
本地验证通过后，相同的检查会在 CI/CD 流程中再次执行。这确保：
- 本地环境的检查结果与远程一致。
- 任何绕过本地检查的变更都会在 CI 中被捕获。
- 部署只在所有检查通过后进行。
为什么这么多层
每一层检查捕获的问题类型不同：
| 层次 | 捕获的问题 | 速度 |
|---|---|---|
| Prettier | 格式不一致 | 毫秒 |
| ESLint | 代码质量问题 | 秒 |
| TypeScript | 类型错误 | 秒 |
| Vitest | 逻辑错误 | 秒 |
| 构建 | 资源缺失、链接断开 | 秒 |
| 端到端 | 功能性问题 | 十秒 |
跳过任何一层都可能让问题溜到生产环境。多层检查的目的不是“做很多事”，而是“用不同的视角检查同一件事”。
接下来
构建验证流程会随着站点功能增加而演进。可能的改进方向：
- 可访问性检查（axe-core）。
- 性能预算检查（Lighthouse CI）。
- 视觉回归测试（截图对比）。
- 内容质量检查（字数、标题长度、图片 alt 文本）。
但核心原则不变：每次部署都应该是可验证的。
评论