发布检查清单

这页没什么玄学，就是推送前看一眼。很多部署失败不是技术难题，只是漏了一个标签、写错一个路径、忘了跑构建。

别笑，大家都这么炸过。

推送前

[ ] pnpm install 能正常完成
[ ] pnpm build 能通过
[ ] 新页面有 frontmatter
[ ] 新页面已经写进 meta.json
[ ] 内部链接能打开
[ ] 外部链接不是随手复制错的
[ ] 代码块语言标记正确
[ ] 没把 token、key、cookie 写进文档

页面内容

检查一下每个页面有没有这些东西：

• 标题能不能说明问题。
• 第一段有没有讲清楚这页干嘛。
• 命令是否完整可复制。
• 配置示例有没有闭合括号。
• 如果有步骤，顺序是否能照着做。
• 如果有坑点，是否是真坑，不是硬编。

文档不用太严肃，但至少别让人看完更迷糊。

MDX 语法

重点看这些：

[ ] JSX 组件标签已闭合
[ ] import 的组件确实用到了
[ ] 代码块围栏数量正确
[ ] JSON 示例没有少逗号或多逗号
[ ] 公式上下留了空行

MDX 的报错有时候看着很吓人，但根因可能只是前面少了一个 </Callout>。别被它唬住。

侧栏

新增页面后，检查对应目录的 meta.json。

例子：

{
  "title": "开始使用",
  "pages": ["quick-start", "configuration", "writing-workflow"]
}

如果页面存在但侧栏没出现，大概率是 pages 里没写。

本地预览

构建通过后，可以本地预览：

pnpm start

然后看：

• 首页是否正常。
• 文档首页是否正常。
• 新页面是否能打开。
• 移动端侧栏是否能用。
• 深色/浅色模式是否正常。

推送后

推送以后看自动构建：

GitHub push
→ Pages 平台开始构建
→ 看日志
→ 部署成功
→ 打开线上页面确认

不要只看到绿色就走。至少点开线上页面看一眼，有些问题构建不一定报错，但页面效果会很怪。

出事时怎么查

按这个顺序：

1. 看构建日志第一条真正的错误。
2. 如果是 MDX，回到对应文件检查标签和代码块。
3. 如果是依赖，确认 pnpm-lock.yaml 和 Node 版本。
4. 如果是路由，检查文件路径和 meta.json。
5. 如果本地正常线上不正常，再看平台配置。

别一出事就到处改配置。一次只改一个变量，不然你最后连自己修好了什么都不知道。

可以晚点再管的东西

这些不是第一优先级：

• 细抠动画。
• 大改主题色。
• SEO 每个字段都填满。
• 为了好看加一堆没用组件。

先让内容稳定。壳子可以慢慢修，空壳再漂亮也只是空壳。