跳到主要内容
版本:Next

上线与更新手册

这份文档只回答两个问题:内容怎么更新、站点怎么上线。每一步都给出可以直接执行的命令,以及执行完应该看到什么结果。

前置条件:Node.js 20 以上(node -v 确认),项目根目录已经 npm install 过一次。

0. 两条链路速查​

我要做什么命令耗时
本地预览(改什么看什么)npm start首次约 20 秒
新增一篇文档npm run new -- docs/<栏目>/<文件>.md秒级
提交前自检npm run check秒级
打包(含全部守门)npm run verify3–5 分钟
只打包不守门npm run build2–3 分钟
本地看打包结果npm run serve秒级

记住一个原则:npm run verify 通过 = 可以上线;没通过就不要打包上线。


1. 更新内容​

1.1 新增一篇文档​

npm run new -- docs/ue/networking/my-topic.md

脚本会生成带完整 frontmatter 的骨架,不修改任何配置文件。侧栏、导航、搜索索引、sitemap 全部自动更新——这是本模板的核心约定,新增内容永远不需要碰代码。

1.2 frontmatter 每个字段都要填​

---
title: 属性复制与 RPC:带宽预算下的取舍 # 页面标题,也会进搜索索引
description: 从每个 Actor 每帧产生的字节数出发…… # 摘要,列表页与 SEO 用它
sidebar_position: 1 # 同级排序,数字小的在上面
tags: [网络, 复制, 带宽] # 标签,会出现在详情页与变更日志
subject_version: "5.8" # 领域维度,取值必须在配置的版本列表里
updated: 2026-11-13 # 最后更新日期,必须是 YYYY-MM-DD
access: free # free / member / pro,付费项构建期直接拒绝
---

字段缺失或格式不对时,npm run check 会逐条告诉你缺哪个、错在哪:

校验文档 9 篇(领域维度字段:subject_version)
frontmatter 校验通过:字段完整,access 全为 free

1.3 加一个新栏目(分类)​

栏目 = 文件夹,顺序与显示名写在文件夹里的 _category_.json:

{
"label": "网络同步",
"position": 3,
"link": {"type": "generated-index"},
"collapsible": true,
"collapsed": true
}

collapsed: true 表示默认收起,读者点标题才展开;当前页所在的分类会自动展开,不用读者再点。collapsible: true 表示允许手动收起。新栏目照抄这一份即可,别写成 false,否则侧栏一进站就是长长一列全展开。

同时要在英文目录放一份孪生声明,否则顶栏的英文名会缺失、npm run check:i18n 会报错:

i18n/en/docusaurus-plugin-content-docs/current/ue/networking/_category_.json

1.4 双语:写中文就必须配英文​

这是本模板唯一有硬性负担的地方。每篇 docs/ 下的文档,都必须在同路径下有一份英文译文:

docs/ue/networking/my-topic.md
i18n/en/docusaurus-plugin-content-docs/current/ue/networking/my-topic.md

译文的要求只有三条,全部由脚本自动检查:

检查项规则
文件名与原文完全同名同路径
正文不允许有成段中文(代码块、行内代码里的中文豁免)
路由字段slug 与 sidebar_position 必须与原文一致

跑一次就知道缺哪篇:

npm run check:i18n
翻译覆盖:9/9 篇(100%)| i18n/en JSON 文案 111 条
翻译检查通过:文档、分类声明与界面文案均有对应译文,且无残留中文

如果暂时不想翻:把这篇文档写进 docs/ 之外(例如项目根目录的 notes/),它就不会被当成页面。但站内文档必须成对,这是构建守卫,绕不过去。

1.5 修改一篇已有文档​

直接改 docs/ 与 i18n/ 两侧的文件即可。需要注意两点:

  1. 同步更新 updated 字段,否则页面底部显示的还是旧日期。
  2. 提交信息决定变更日志的分类(见 1.6)。

1.6 变更日志是自动生成的​

不要手动编辑 docs/changelog/<年份>.md,它整篇由脚本生成,下次生成会覆盖。

npm run changelog # 生成/更新,写入中英两份
npm run changelog:check # 只检查是否有提交还没进日志(CI 用)

分类规则来自提交信息,靠前缀覆盖默认判断:

提交信息写法分类什么时候用
docs: 补充属性复制条件新增新增页面
fix: 修正量化数值修订内容改动
[勘误] 修正回调线程结论勘误推翻旧结论,读者按旧文实现过
[破坏性更正] 重写排队章节破坏性更正整段结论作废

只有前两种是自动判断的;「勘误」与「破坏性更正」必须手动写前缀,因为机器分不清「补充」和「推翻」。这两类恰恰是读者最需要看到的。

1.7 删除或移动文档​

操作要做的事
删除删 docs/ 与 i18n/ 两侧文件,然后 npm run gen:index 重建索引
移动/改名两侧同步移动;旧链接会 404,如果外部引用过,改完在目的目录加一个 slug 保持原 URL
调整顺序只改 sidebar_position,不要改文件名

移动是高危操作:文件名即 URL。若某篇已经被外部引用,两种处理方式——保留 slug 指向旧路径,或在 docusaurus.config.js 的 redirects 里加插件。推荐前者,零依赖。

1.8 发一个版本快照​

内容积累到可以冻结时(例如对应引擎大版本),生成一份只读快照:

npx docusaurus docs:version 5.8

生成 versions.json、versioned_docs/version-5.8/、versioned_sidebars/。之后:

  • current 版本继续演进,URL 在根路径
  • 快照固定在 /5.8/,内容不再跟随主干变化
  • 顶栏不会出现版本下拉(按站点定位刻意关掉),快照靠链接直接访问;需要切换器时在 docusaurus.config.js 的 navbarItems 里加 {type: 'docsVersionDropdown', position: 'right'}

注意:快照里的文档不会自动同步后续修订。如果发现快照里有错,要么改快照文件本身,要么发一个新的小版本。

1.9 换一整套内容包(换主题)​

只改 site.config.js + docs/,模板层(src/、scripts/、docusaurus.config.js、sidebars.js)一行都不用动。完整步骤见 内容包替换清单。

一个必读的坑:内容包必须在 docs/ 根放一篇 slug: / 的导览文档,否则顶栏「首页」断链,构建直接失败。


2. 打包上线​

2.1 上线前必须做的四件事​

这四项不做,站点能打开但搜索引擎和分享链接会出问题:

#事项具体操作不做会怎样
1设置真实域名打包时带 SITE_URL=https://你的域名canonical、sitemap、robots.txt、llms.txt 全部指向占位域名 example.com,搜索引擎收录错误地址
2确认 robots 与 sitemap打包后检查 build/robots.txt 有两个 sitemap 入口爬虫不知道 sitemap 在哪
3DNS 与 HTTPS域名解析到托管方,开启自动证书浏览器标「不安全」,微信内打开可能被拦
4替换页脚与联系方式改 site.config.js 的 footer 与 links分享出去是模板默认信息

SITE_URL 是构建期变量,每次打包都要带。它的影响范围:

canonical / hreflang → docusaurus.config.js
sitemap.xml(两份) → 构建时生成
robots.txt → scripts/gen-site-meta.mjs
llms.txt → scripts/gen-site-meta.mjs

2.2 一条命令打包​

SITE_URL=https://docs.your-domain.com npm run verify

Windows PowerShell:

$env:SITE_URL="https://docs.your-domain.com"; npm run verify

verify 会按顺序跑六道关卡,任何一道失败就停下,不会产出半成品:

顺序关卡拦什么
1check-template-purity模板层混入领域词(换主题时会炸)
2changelog:check有提交没进变更日志
3check-frontmatter字段缺失、access 非 free、版本值不在列表
4check-i18n缺译文、译文里有中文、分类孪生缺失
5gen-search-index生成搜索索引
6gen-site-meta + docusaurus build生成 robots/llms,编译全站

成功的标志是最后两行 SUCCESS:

[SUCCESS] Generated static files in "build".
[SUCCESS] Generated static files in "build/en".

2.3 产物长什么样​

build/
├── index.html 中文首页
├── 404.html
├── robots.txt ← 由脚本生成,不要手改
├── llms.txt ← 给 AI 爬虫的站点摘要
├── search-index.json ← 本地搜索索引
├── sitemap.xml 中文 42 条
├── en/
│ ├── index.html 英文首页
│ ├── sitemap.xml 英文 42 条
│ └── ...
├── ue/… conventions/… changelog/…
└── assets/ 带哈希的 js/css

整个 build/ 目录就是站点,纯静态,没有任何服务端依赖。上传即上线。

2.4 部署方式​

方式 A:Nginx(自有服务器)

server {
listen 80;
server_name docs.your-domain.com;
root /var/www/docs-ue/build;
index index.html;

# 静态资源带哈希,长缓存
location /assets/ {
expires 1y;
add_header Cache-Control "public, immutable";
}

# HTML 短缓存,保证内容更新能立刻看到
location ~* \.html$ {
expires 5m;
add_header Cache-Control "public, must-revalidate";
}

# 目录式路由:/ue/networking/foo → /ue/networking/foo/index.html
location / {
try_files $uri $uri/ $uri/index.html =404;
}

error_page 404 /404.html;
}

try_files 这一行不能省,否则所有子页面 404。Docusaurus 生成的是目录式路由。

方式 B:Vercel / Netlify(推荐,零运维)

项值
构建命令SITE_URL=https://docs.your-domain.com npm run verify
输出目录build
Node 版本20
环境变量SITE_URL = 正式域名

两者都会自动处理 HTTPS 与目录路由,不需要额外配置。

方式 C:对象存储 + CDN(阿里云 OSS / 腾讯云 COS)

  1. 把 build/ 整个上传,保持目录结构
  2. 静态网站托管首页设为 index.html,错误页设为 404.html
  3. 关键:开启「子目录 index.html 优先」,否则 /ue/foo/ 打不开
  4. CDN 缓存:/assets/* 一年,/*.html 五分钟

2.5 上线后逐项校验​

不要只看首页能不能打开。六条都要过:

curl -I https://docs.your-domain.com/
curl -I https://docs.your-domain.com/robots.txt
curl -I https://docs.your-domain.com/en/
curl -I https://docs.your-domain.com/sitemap.xml
curl -I https://docs.your-domain.com/en/sitemap.xml
curl -s https://docs.your-domain.com/robots.txt
检查点期望
首页200,content-type: text/html
/robots.txt200,内容里能看到两个 Sitemap: 行,域名是正式域名
/en/200,页面语言为英文
两个 sitemap200,各 42 条左右
随机点三个内页200,侧栏高亮正确
手机打开顶栏出现搜索图标,点开能搜到结果

最后再确认一次:在浏览器里查看网页源代码,看 canonical 是不是正式域名。 如果是 example.com,说明打包时 SITE_URL 没生效。

2.6 回滚​

静态站回滚就是换回上一份产物:

场景做法
部署在 Vercel/Netlify控制台选择上一个 Deploy,一键回退
自有服务器部署时保留上一版目录,ln -sfn 切换软链
对象存储开启版本控制,回滚到指定版本

建议:用带时间戳的目录保留最近三版(releases/2026-11-13-1800/),出问题时切软链,秒级恢复。


3. 上线前检查清单​

打勾之前不要对外发布。

  • SITE_URL 已设为正式域名,打包后 canonical 正确
  • build/robots.txt 里有两个 Sitemap: 行
  • 中英文各抽查三个页面,内容与侧栏正常
  • npm run verify 全绿(六道关卡 + 两次 SUCCESS)
  • 手机宽度下顶栏搜索可用
  • 页脚联系方式、备案号、版权年份已替换为真实信息
  • HTTPS 证书有效,http 自动跳 https
  • 404 页面能正常显示(随便访问一个不存在的路径)
  • 站点可被外部抓取:curl -A "Googlebot" https://域名/ 返回 200(不是登录墙)
  • 备份了当次产物

其中「可被外部抓取」这一条,是后续申请 Algolia 全文搜索的前提——它需要先能爬取整站。


4. 故障排查​

现象原因处理
子页面全 404,首页正常服务器没做目录路由补 try_files,或开启「子目录 index.html 优先」
构建报 Broken link链接指向不存在页面;换内容包时缺 slug: / 导览页按报错路径修正,或补导览文档
Subject.field 未声明site.config.js 的 subject.field 被改动或删除恢复配置,脚本靠它决定 frontmatter 字段名
英文页显示中文缺译文文件,框架静默回退npm run check:i18n 看缺哪篇
搜不到新文档索引没重建npm run gen:index;dev 下应当自动重建
变更日志报「有提交未记录」提交后没重新生成npm run changelog 再提交
打包卡在 docusaurus build内存不足或断链看日志里第一条 Error,通常是断链
页面样式错乱,像没加载 CSSbaseUrl 与实际部署路径不一致部署到子路径时改 docusaurus.config.js 的 baseUrl

一个通用排查技巧:构建失败时,永远看日志里第一条 error,后面的多半是它的连锁反应。


5. 一句话总结​

内容更新 = 写文件 + 配英文 + 跑 npm run check;上线 = 带 SITE_URL 跑 npm run verify + 上传 build/。

其余所有事(侧栏、搜索索引、sitemap、robots、变更日志、双语路由)都由脚本自动完成,不需要手工维护。