部署指南

写完文档不部署也不是不行，只是它会永远躺在本地，像一个只有你自己知道的秘密基地。

这个模板是 Next.js + Fumadocs，适合部署到支持 Next.js 的平台。比如 EdgeOne Pages、Vercel、Netlify，或者你自己的服务器。

先本地构建

推送前先跑 pnpm build。本地都构建不过，线上平台也不会突然变聪明。别把自动构建当许愿池。

最小部署流程

本地检查

pnpm install
pnpm build

如果这一步失败，先修本地错误。常见原因是 MDX 标签没闭合、链接写错、组件 import 漏了。

推送到 GitHub

git add .
git commit -m "docs: update documentation"
git push

如果你接了自动构建，推送后平台会自己开始部署。

在平台选择框架

部署平台里选择 Next.js。一般配置是：

Install Command: pnpm install
Build Command: pnpm build
Output Directory: 由平台按 Next.js 自动处理

如果平台要求指定输出目录，先看它对 Next.js 的说明，别瞎填 .next 或 out。

等构建日志

部署时盯构建日志，不要只看最终红绿灯。

真正有用的信息一般在中间几行，比如：

Error: Expected a closing tag for <Callout>

这种就不是平台问题，是文档写炸了。

EdgeOne Pages 思路

如果你用 EdgeOne Pages，大致就是：

连接 GitHub 仓库。
选择这个项目。
框架选 Next.js。
安装命令填 pnpm install。
构建命令填 pnpm build。
保存并部署。

第一次部署成功后，后面只要 push 到对应分支，它就会自动重建。

Vercel 思路

Vercel 对 Next.js 支持最省心：

Import Git Repository。
选仓库。
Framework Preset 选 Next.js。
包管理器识别为 pnpm。
Deploy。

如果只是想快速验证站点效果，Vercel 很适合。缺点是你最后可能又多一个平台后台，别问，个人项目就是这样越养越多。

自己服务器部署

如果你想放到自己的服务器，可以走普通 Next.js 服务：

pnpm install
pnpm build
pnpm start

然后用 Nginx 或 Caddy 反代到对应端口。

这条路自由度高，但维护成本也更高。只是一个文档站的话，Pages 平台通常更省心。

环境变量

普通文档站通常不需要环境变量。

如果以后接搜索、统计、私有 API，再考虑加。环境变量不要写进仓库，尤其是 token、key、cookie 这种东西。

.env.local       本地开发用
平台环境变量     线上构建/运行用
仓库代码         不放秘密

这不是安全废话，是防止你哪天把 token 推公开仓库，然后半夜开始骂自己。

部署后检查

部署成功不等于没问题。至少看一遍：

首页能不能打开。
/docs 能不能打开。
侧栏顺序对不对。
搜索有没有明显异常。
代码块样式是否正常。
LaTeX 公式有没有渲染。
移动端菜单能不能点。
404 页面是不是能正常处理。

常见失败原因

MDX 语法错误

最常见。比如组件标签没闭合：

<Callout title="提示" type="info">
  内容

修法：补上 </Callout>。

import 写错

比如组件路径拼错，构建会报模块找不到。

先对照已有页面里能工作的 import，不要凭感觉写。

Node 版本太旧

Next 新版本对 Node 版本要求比较高。线上平台如果默认 Node 太老，就在平台设置里调新版本。

输出目录填错

Next.js 项目不要照搬纯静态站的输出目录。平台支持 Next.js 时，让它按框架处理。