部署發布

本站是純靜態站點，建置產物可部署到任意靜態託管平台。

建置

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（無需寫程式碼）

成本估算