生产上线清单

这份项目已经具备 Next.js、Fumadocs MDX、中文界面、本地搜索和示例文档。正式上线前，重点是补齐部署目标、站点配置、内容质量和发布流程。

目前已经具备

• Next.js + Fumadocs MDX 文档站结构
• content/docs 内容目录
• 中文 UI 翻译和中文示例内容
• 本地 Orama 搜索，并已加入轻量中文 tokenizer
• package-lock.json，可以用 npm 稳定安装依赖
• types:check 和 lint 校验脚本

上线前还缺什么

1. 生产构建验证

每次上线前至少跑一遍：

npm.cmd run types:check
npm.cmd run lint
npm.cmd run build

前两个用于检查文档、类型和代码规范；build 用于确认生产构建能正常生成。

2. 部署平台

当前项目包含 API Route、OG 图片路由和 LLM 文档路由，不适合直接丢到普通静态文件托管里。推荐选择支持 Next.js 服务端运行时的平台。

常见选择：

• Vercel：最省事，连接 Git 仓库后自动识别 Next.js。
• 自己的服务器：安装 Node.js，执行 npm ci、npm run build、npm run start。
• Docker 或云主机：需要补 Dockerfile、反向代理和进程守护。

如果以后只想部署到纯静态托管，需要单独改造搜索、OG 图片和路由输出策略。

3. Node.js 版本

生产环境要固定 Node.js 版本，避免本地能跑、线上构建失败。

建议：

• 本机当前是 Node.js 24，可在生产环境使用同一主版本。
• 如果部署平台允许配置版本，优先固定在 22 或 24 这类较新的 LTS/稳定版本。
• 可以后续在 package.json 增加 engines.node，让部署平台更明确。

4. 站点基础信息

上线前建议补齐：

• 正式站点名和导航名称
• favicon、Logo、品牌色
• 首页标题、描述和 Open Graph 信息
• 生产域名、HTTPS、备案或合规信息
• robots.txt、sitemap.xml、canonical URL

5. 内容替换

上线前需要把脚手架示例内容替换成真实内容：

• 删除或改写「组件示例」
• 完成首页和文档首页
• 检查侧边栏顺序
• 检查每篇文档的 title 和 description
• 检查外链是否有效

6. 环境变量

当前项目没有必须的密钥。以后如果接入这些能力，需要补 .env.example 和生产环境变量：

• 统计分析
• 第三方搜索
• AI 问答
• 评论系统
• 私有接口或鉴权

不要把真实密钥写入 MDX、README 或 Git 仓库。

7. 发布和回滚流程

最小可用流程：

npm.cmd ci
npm.cmd run build
npm.cmd run start

正式团队流程建议：

• 所有修改先进入 Git
• 主分支自动部署生产环境
• 分支或 PR 自动生成预览环境
• 上线后检查首页、文档页、搜索、404 页面
• 保留上一个可回滚版本

最小上线版本

如果只是先上线一个可访问的中文文档站，最少补这几项：

• 选择 Vercel 或支持 Next.js 的服务器
• 把项目推到 Git 仓库
• 跑通 npm.cmd run build
• 替换站点名、首页文案和示例文档
• 绑定域名和 HTTPS

完成这些后，这个项目就可以作为生产文档站的第一版。