部署发布

本站是纯静态站点，构建产物可部署到任意静态托管平台。

构建

bash

npm run docs:build:all

输出目录为 docs/.vitepress/dist。

提示：npm run docs:build 默认只构建简体中文（构建时会询问是否需要构建多语言版本）；发布完整多语言站点请用 npm run docs:build:all，日常开发可用 npm run docs:dev 实时预览。

方式一：GitHub Pages

在仓库 Settings → Pages 中选择部署分支与目录；
或使用 GitHub Actions 自动构建：

yaml

name: Deploy Docs

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run docs:build:all
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

方式二：Vercel / Netlify

以 Vercel 为例：

导入仓库；
构建命令：npm run docs:build:all；
输出目录：docs/.vitepress/dist；
点击部署即可，支持每次推送自动部署与预览分支。

方式三：Nginx

bash

# 将构建产物上传到服务器后
scp -r docs/.vitepress/dist user@server:/var/www/docs

Nginx 配置示例：

nginx

server {
  listen 80;
  server_name docs.example.com;

  root /var/www/docs;
  index index.html;

  # 前端路由回退
  location / {
    try_files $uri $uri/ /index.html;
  }
}

自定义域名与 HTTPS

在托管平台绑定自定义域名；
配置 CNAME 记录指向平台；
平台自动签发并续期 HTTPS 证书。

方式四：腾讯云 COS + CDN

国内访问体验最好的低成本方案之一，对象存储 + CDN 加速，适合面向中国大陆用户的站点。

1. 准备

腾讯云账号（新用户可领取免费额度，通常含标准存储 10GB 及部分流量，有效期数月）；
已备案域名（使用中国大陆 CDN 加速域名必须完成 ICP 备案，审核约 1-3 周，免费）。

备案流程详解（腾讯云 ICP 备案）

前置条件

域名已完成实名认证（在域名注册商处，通常 1-3 天生效）；
腾讯云账号已完成实名认证，且拥有腾讯云服务器/轻量应用服务器等备案云资源（备案必须绑定云资源）；
网站内容须符合《非经营性互联网信息服务备案管理办法》，个人备案不得涉及经营性内容。

步骤	操作	所需材料	预计时间
1. 验证域名	登录腾讯云备案控制台，输入域名，系统自动识别备案类型（首次备案/接入备案等）	备案域名	即时
2. 填写资料	填写主体信息（个人姓名/企业名称、证件号）与服务信息（网站名称、域名、网站负责人、服务内容），上传证件照片与核验单	身份证正反面、手持照片（App 人脸核验）、网站负责人信息、核验单（自动生成）	视准备情况
3. 腾讯云初审	腾讯云审核资料真实性、完整性	—	1-2 个工作日
4. 短信核验	工信部下发验证码，24 小时内登录工信部备案系统完成核验	收到的短信验证码	24 小时内
5. 管局审核	当地通信管理局最终审核	—	最长 20 个工作日
6. 备案完成	收到短信/邮件通知，获得备案号	—	以通知为准

备案通过后还需做两件事：

在网站底部展示备案号，并超链接至工信部备案系统 https://beian.miit.gov.cn，例如「粤ICP备2026000000号」；
建议同时申请公安备案（备案通过后 30 日内），部分省份强制要求。

备案小贴士

个人首次备案一般 1-2 周可完成，各地管局效率不同；
备案期间可以先部署在 COS 默认域名或海外节点上线，备案通过后再切换自定义域名；
备案是免费服务，注意甄别付费代办（代办仅提供材料整理指导）。

2. 创建存储桶

控制台进入对象存储 COS，创建存储桶；
地域就近选择（如广州 ap-guangzhou）；
访问权限选择公有读私有写；
开启「静态网站」功能，索引文档填 index.html，错误文档填 404.html。

3. 上传构建产物

构建后上传 docs/.vitepress/dist 目录：

bash

npm run docs:build:all

# 方式一：控制台上传（对象 → 上传文件夹，选 dist 下所有文件）
# 方式二：使用 COSCLI 命令行工具
pip install coscmd
coscmd config -a <SecretId> -s <SecretKey> -b <bucket-name>-<appid> -r ap-guangzhou
coscmd upload -rs ./docs/.vitepress/dist/ /
coscmd list -r /

4. 接入 CDN 加速

控制台进入内容分发网络 CDN，添加加速域名；
加速区域选中国大陆（未备案选中国香港/海外，速度一般）；
源站类型选对象存储 COS，选择刚创建的存储桶；
域名接入方式选 CNAME，按提示到域名服务商处添加 CNAME 记录；
等待 CNAME 生效（约 10 分钟），开启「回源跟随 301/302」与「Range 回源」。

5. 配置 HTTPS

5.1 申请免费证书

控制台进入 SSL 证书，选择「申请免费证书」；
证书类型选 DV（域名型），绑定加速域名；
验证方式选自动 DNS 验证（域名在腾讯云/已托管解析时一键完成），等待签发（几分钟到几小时）。

5.2 在 CDN 上启用

CDN「域名管理 → HTTPS 配置」中勾选已签发的证书；
开启「HTTP 强制跳转 HTTPS」（建议开启，跳转状态码选 301）；
开启后首次访问前可在「刷新预热」中对首页做 URL 预热，提升首访速度。

计费说明

DV 证书免费，无需续费成本（到期前系统提醒，可重新申请）；
注意：CDN 的 HTTPS 请求数属于增值服务，按 0.04 元/万次计费——文档站请求量小（月均几十万次），约几元，可忽略；如完全不想产生该费用，可在「增值服务」中关闭 HTTPS 计费项（不推荐，会失去加密）。

5.3 验证部署结果

bash

curl -I https://docs.example.com
# 期望返回：HTTP/2 200
# 响应头包含：strict-transport-security 等安全头（可后续在 CDN 响应头配置中自定义）

5.4 CNAME 配置说明

接入 CDN 时，加速域名会被分配一个 .cdn.dnsv1.com 结尾的 CNAME 记录，需到域名解析服务商处添加：

记录类型	主机记录	记录值	TTL
CNAME	`docs`	`docs.example.com.cdn.dnsv1.com`	600

生效时间通常 10 分钟到 1 小时（取决于 TTL）；
配置错误（如误配成 A 记录）会导致域名解析到 CDN 失败，访问报错；
验证：nslookup docs.example.com，返回 CNAME 目标即成功。

6. 缓存配置

静态文档站点建议对资源设置长缓存（CDN 命中率可达 99%+，几乎无回源流量）。在 CDN 控制台「域名管理 → 缓存配置」中操作。

6.1 推荐的缓存规则

优先级	匹配类型	内容	缓存时间	说明
1	文件后缀	`.html`	10 分钟	内容更新后尽快生效
2	文件后缀	`.js` `.css`	30 天	VitePress 构建产物带 hash，放心长缓存
3	文件后缀	`.png` `.jpg` `.svg` `.webp` `.ico`	30 天	图片静态资源
4	文件后缀	`.woff` `.woff2` `.ttf`	30 天	字体文件
5	全部文件	`*`	30 天	兜底规则

6.2 缓存命中与命中率

缓存命中后，CDN 直接返回边缘节点内容，不产生回源流量（省下 0.15 元/GB 的回源费）；
命中率可在控制台「统计分析 → 命中率」查看，文档站通常稳定在 99% 以上；
若命中率低，检查是否开启了「忽略查询字符串」：开启后 page.html?ref=a 与 page.html?ref=b 命中同一缓存。

6.3 缓存刷新与预热

刷新：内容更新后执行，清除边缘节点缓存（刷新 URL 实时生效；按目录刷新约 5 分钟）；
预热：将资源提前缓存到边缘节点，用于上线新版本或大促，首次访问不再回源；
控制台路径：「刷新预热」→ 输入 URL/目录 → 提交；
自动化的做法：发布脚本里在 coscmd upload 之后调用 CDN 刷新 API（DescribeCdnHosts / 刷新 URL 接口），或使用 COS 事件通知触发。

6.4 浏览器缓存（二级缓存）

CDN 节点缓存之外，浏览器自身也会缓存资源，可在 COS 或 CDN 的「HTTP 响应头配置」中为静态资源添加：

http

Cache-Control: public, max-age=2592000   # 30 天，用于带 hash 的静态资源
Cache-Control: no-cache                   # HTML 每次回源验证（配合 10 分钟节点缓存）

6.5 状态码缓存

状态码	建议缓存时间	说明
`200`	跟随缓存规则	正常响应
`404`	10 秒	避免永久缓存错误页，导致修复后仍报 404
`403/500/502`	0	服务器错误不缓存，便于快速恢复

7. 发布脚本自动化（上传 + 自动刷新）

本项目已内置一键发布脚本 scripts/deploy.mjs，完成「构建 → 增量上传 → 自动刷新 CDN 缓存」全流程。

7.1 环境准备

安装依赖：npm i -D cos-nodejs-sdk-v5 tencentcloud-sdk-nodejs-cdn；
在访问管理 CAM 创建 API 密钥；
复制 .env.example 为 .env 并填写：

bash

TENCENTCLOUD_SECRET_ID=your-secret-id
TENCENTCLOUD_SECRET_KEY=your-secret-key
COS_BUCKET=your-bucket-1250000000    # 含 appid 后缀
COS_REGION=ap-guangzhou              # 与存储桶地域一致
CDN_DOMAIN=docs.example.com          # 加速域名，设置后自动刷新 CDN

7.2 用法

bash

npm run deploy                  # 正式发布：构建 + 备份 + 上传 + 刷新 CDN
npm run deploy -- --dry-run     # 演练：只输出执行计划，不实际变更
npm run deploy -- --refresh-all # 改为整站目录刷新（默认只刷新 .html）
npm run deploy -- --skip-build  # 跳过构建，直接上传现有产物
npm run deploy -- --no-backup   # 跳过发布前版本备份

7.3 脚本执行流程

步骤	操作	说明
1	`npm run docs:build:all`	构建静态站点
2	收集本地文件	计算每个文件的 MD5
3	列出远端对象	分页获取 COS 已有文件（MD5 存于自定义 header）
4	计算差异	MD5 相同跳过；本地已删除的远端文件自动清理
5	备份当前版本	发布前把线上内容快照到 `__backup/<时间戳>/`（COS 同桶复制，零流量），保留最近 10 个版本
6	增量上传	只上传变化的文件，HTML 加 `Cache-Control: no-cache`，静态资源 30 天
7	刷新 CDN	默认精准刷新全部 `.html` URL（配额充足）；`--refresh-all` 切换整站目录刷新

为什么只刷 HTML？ 静态资源文件名带 hash，内容变了文件名就变，无需刷新；HTML 缓存 10 分钟，刷新后立即生效。这样每次发布只需 10 条刷新配额。

7.4 CI/CD 集成（GitHub Actions 示例）

yaml

name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ['docs/**', 'package.json']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run docs:build:all
      - name: 发布到 COS + 刷新 CDN
        run: node scripts/deploy.mjs --skip-build
        env:
          TENCENTCLOUD_SECRET_ID: ${{ secrets.TENCENTCLOUD_SECRET_ID }}
          TENCENTCLOUD_SECRET_KEY: ${{ secrets.TENCENTCLOUD_SECRET_KEY }}
          COS_BUCKET: ${{ secrets.COS_BUCKET }}
          COS_REGION: ap-guangzhou
          CDN_DOMAIN: ${{ secrets.CDN_DOMAIN }}

在仓库 Settings → Secrets 中配置上述密钥后，每次推送 docs/ 变更即自动发布。

7.5 版本备份与回滚

发布前脚本会自动把当前线上内容快照到 __backup/<时间戳>/ 前缀（COS 同桶复制，不产生流量费用），保留最近 10 个版本，发布出问题可随时回滚。

bash

npm run rollback                            # 列出所有备份版本（时间 + 文件数）
npm run rollback -- --to 20260831103000     # 回滚到指定版本
npm run rollback -- --to 20260831103000 --prune    # 回滚并删除该版本之外的多余文件
npm run rollback -- --to 20260831103000 --dry-run  # 演练，只输出执行计划
npm run rollback -- --to 20260831103000 --refresh-all  # 回滚后整站刷新（默认只刷 .html）

回滚原理：把备份对象复制回站点根目录（保留原缓存头），--prune 时删除当前线上多出来的文件，随后自动刷新 CDN 缓存，站点立即恢复。

安全设计

备份在上传之前完成，备份失败则视为发布风险，先解决再继续；
回滚只恢复备份中的文件，不触碰其他备份版本（互不影响）；
--dry-run 全程离线，可用假密钥先演练。

7.6 自动生成更新日志

内置 scripts/changelog.mjs，支持两种模式（自动检测 git 仓库）：

bash

npm run changelog                  # 打印最近 30 天更新日志
npm run changelog -- --days 7      # 只看最近 7 天
npm run changelog -- --write       # 写入 CHANGELOG.md
npm run changelog -- --from <ref>  # git 模式：从指定 ref（tag/hash/HEAD~10）开始
npm run changelog -- --files       # 强制文件模式（无需 git）

git 模式（推荐）：基于 git log，按 Conventional Commit 自动分类（feat→新增、fix→修复、docs→文档、perf→性能等）；
文件模式（自动降级）：无 git 仓库时扫描 docs/ 下 Markdown 文件的修改时间与标题，按日期分组生成。

建议配合发布流程：先 npm run changelog -- --write 更新日志，再 npm run deploy 发布。

7.7 轻量替代：coscli + tccli（无需写代码）

如果不希望引入 Node SDK，也可用腾讯云官方命令行工具：

bash

# 1. 安装 coscli（增量同步 + 删除多余文件）
curl -L https://github.com/tencentyun/coscli/releases/latest/download/coscli-darwin-amd64 -o /usr/local/bin/coscli
chmod +x /usr/local/bin/coscli
coscli config  # 按提示填写密钥

npm run docs:build:all
coscli sync ./docs/.vitepress/dist/ cos://your-bucket/ -r --delete --include ".*"

# 2. 安装 tccli 并刷新 CDN（腾讯云官方 CLI）
pip install tccli
tccli configure  # 配置密钥
tccli cdn PurgeUrlsCache --Urls '["https://docs.example.com/index.html"]' --Area mainland

成本估算

以典型文档站（站点 100MB、月访问 1 万次、CDN 流量约 2GB）为例：

计费项	单价	月成本估算
COS 标准存储	0.118 元/GB/月	约 0.01 元（新用户免费额度覆盖）
COS 请求费	0.01 元/万次	约 0.01 元
CDN 流量（0-2TB 阶梯）	0.21 元/GB	约 0.42 元
CDN 回源流量	0.15 元/GB	约 0 元（缓存命中率 99%+）
HTTPS 证书	免费	0 元
合计	—	约 0.5 元/月

费用提示

流量越大 CDN 单价越低：2-10TB 区间 0.20 元/GB、10-50TB 区间 0.18 元/GB；
可购买 CDN 流量包进一步降低单价（常有促销）；
唯一额外成本是域名（常见后缀约 20-60 元/年，新用户首年常有 1 元活动），备案本身免费；
若未备案，也可直接用 COS 自带的默认访问域名，但无法使用自定义域名且外网下行按 0.5 元/GB 计费，故推荐备案 + CDN 组合。

提示

国内环境除腾讯云 COS + CDN 外，也可选用阿里云 OSS + CDN、七牛云、又拍云等对象存储托管静态站点，成本与操作类似。

部署发布 ​

构建 ​

方式一：GitHub Pages ​

方式二：Vercel / Netlify ​

方式三：Nginx ​

自定义域名与 HTTPS ​

方式四：腾讯云 COS + CDN ​

1. 准备 ​

备案流程详解（腾讯云 ICP 备案） ​

2. 创建存储桶 ​

3. 上传构建产物 ​

4. 接入 CDN 加速 ​

5. 配置 HTTPS ​

5.1 申请免费证书 ​

5.2 在 CDN 上启用 ​

5.3 验证部署结果 ​

5.4 CNAME 配置说明 ​

6. 缓存配置 ​

6.1 推荐的缓存规则 ​

6.2 缓存命中与命中率 ​

6.3 缓存刷新与预热 ​

6.4 浏览器缓存（二级缓存） ​

6.5 状态码缓存 ​

7. 发布脚本自动化（上传 + 自动刷新） ​

7.1 环境准备 ​

7.2 用法 ​

7.3 脚本执行流程 ​

7.4 CI/CD 集成（GitHub Actions 示例） ​

7.5 版本备份与回滚 ​

7.6 自动生成更新日志 ​

7.7 轻量替代：coscli + tccli（无需写代码） ​

成本估算 ​

部署发布

构建

方式一：GitHub Pages

方式二：Vercel / Netlify

方式三：Nginx

自定义域名与 HTTPS

方式四：腾讯云 COS + CDN

1. 准备

备案流程详解（腾讯云 ICP 备案）

2. 创建存储桶

3. 上传构建产物

4. 接入 CDN 加速

5. 配置 HTTPS

5.1 申请免费证书

5.2 在 CDN 上启用

5.3 验证部署结果

5.4 CNAME 配置说明

6. 缓存配置

6.1 推荐的缓存规则

6.2 缓存命中与命中率

6.3 缓存刷新与预热

6.4 浏览器缓存（二级缓存）

6.5 状态码缓存

7. 发布脚本自动化（上传 + 自动刷新）

7.1 环境准备

7.2 用法

7.3 脚本执行流程

7.4 CI/CD 集成（GitHub Actions 示例）

7.5 版本备份与回滚

7.6 自动生成更新日志

7.7 轻量替代：coscli + tccli（无需写代码）

成本估算