部署说明：Cloudflare Pages

本站是 VitePress 静态站点，产物通过 wrangler 直传 Cloudflare Pages。 Gitee 仅作源码仓库（dev 开发 / master 稳定），不再托管页面。

• 生产地址：https://sunqy-doc.pages.dev
• 本地预览：npm run docs:dev → http://localhost:5173/

---

1. 首次使用：授权 wrangler（只需做一次）

wrangler 需要绑定你的 Cloudflare 账号。

npx wrangler login

执行后会自动打开浏览器，登录 Cloudflare（没有账号就免费注册一个）， 点「Allow」授权。授权成功后本地会保存凭据，之后不再需要重复登录。

验证授权是否成功：

npx wrangler whoami

能输出你的账号邮箱即表示成功。

---

2. 日常部署：一条命令

npm run deploy

会自动完成：

1. npm run docs:build 构建到 .vitepress/dist
2. wrangler pages deploy ... --branch main 上传产物到 Cloudflare Pages 的 Production 环境

注意：wrangler pages deploy 不会自动创建项目。若报 Project not found，先手动创建一次：

npx wrangler pages project create sunqy-doc --production-branch main

另外，如果省略 --branch main，wrangler 会部署到 Preview 环境，主域名 sunqy-doc.pages.dev 将显示 "Nothing is here yet"。package.json 里的脚本已经加了 --branch main，日常直接 npm run deploy 即可。

---

3. 路径配置（重要）

Cloudflare Pages 的默认域名是根路径，所以 base 必须是 /。

配置在 .vitepress/config.ts：

base: process.env.VITE_BASE || '/'

若以后部署到子路径（例如 GitHub Pages 的 xxx.github.io/doc/），用环境变量覆盖：

VITE_BASE=/doc/ npm run docs:build

改了 base 必须重新构建，否则页面样式和跳转会 404。

---

4. 分支模型

分支	用途	说明
dev	开发源码	日常写文档在这
master	稳定源码	dev 验证后合并进来
main	产物分支	已废弃（Gitee Pages 下线，产物改由 wrangler 上传）

main 分支不再更新，可忽略或在 Gitee 控制台删除。

---

5. 常见问题

Q：wrangler: command not found 先装依赖：npm install（wrangler 已加入 devDependencies）。

Q：部署后页面样式全丢 / 404base 配错了。确认 .vitepress/config.ts 里 base 是 /，然后重新构建再部署。

Q：想换项目名 改 package.json 里 deploy:cf 的 --project-name，以及 deploy.sh 里的 PROJECT_NAME。 换名后需先创建对应项目：npx wrangler pages project create 新项目名 --production-branch main

Q：想绑自己的域名 到 Cloudflare 控制台 → Workers & Pages → 你的项目 → Custom domains → 添加域名。 （国内访问若走自定义域名需注意备案要求；.pages.dev 默认域名无需备案。）

Q：构建时报 [safe-delete] 操作失败 本机 Coding 插件会 hook Node 的 rmSync，导致 VitePress 清空 dist 失败。 构建/部署前先禁用它：

$env:CODEBUDDY_SAFE_DELETE_ENABLED='0'
npm run deploy

Q：deploy.sh 用 PowerShell 跑报错deploy.sh 需用 Git Bash 执行；日常直接用 npm run deploy（纯 npm 命令链，不调 bash）：

npm run deploy

或在 Git Bash 中：

& "D:\sortware\Git\bin\bash.exe" "D:/webstromProject/doc/deploy.sh"

---

6. 部署纪律

提交 ≠ 部署。 本文档库遵循以下约定：

动作	时机
提交源码并推送 dev	每完成一个阶段即可提交
npm run deploy	仅在本地验证通过后，由使用者明确要求才执行

建议流程：

1. npm run docs:dev 本地预览确认渲染与链接
2. npm run docs:build 确认构建无报错
3. 确认无误后再 npm run deploy
4. 打开 https://sunqy-doc.pages.dev 复核（Ctrl+F5 强刷）

---

7. PWA 离线缓存（切页加速）

站点通过 vite-plugin-pwa 生成了 Service Worker（sw.js），构建时把全部页面 chunk 和静态资源预缓存到浏览器本地：

• 效果：完整加载过一次站点后，切换页面走本地缓存、0 网络请求，秒开；断网也能继续阅读。
• 动机：.pages.dev 在国内延迟高，VitePress 切页需按需下载 chunk，每个请求都被高延迟放大。
• 配置位置：.vitepress/config.ts 的 vite.plugins → VitePWA，注册逻辑在 .vitepress/theme/index.ts。
• 更新机制：registerType: 'autoUpdate' —— 发布新版本后，浏览器后台自动拉取新 SW 并激活，用户下次打开即用新版，无需手动干预。
• 本地搜索索引（@localSearchIndex*）体积大且仅打开搜索时才需要，已通过 globIgnores 排除预缓存。
• 验证方法：DevTools → Application → Service Workers 查看 SW 状态；Network 面板切页时应看不到新的文档请求（chunk 显示 from ServiceWorker / disk cache）。
• 注意：本地 npm run docs:dev 默认不启用 SW（devOptions 未开启），属正常现象；构建产物才带缓存。