在 Cloudflare 控制台即可完成部署和配置，无需安装开发工具或编辑代码。模板默认读取示例仓库 main 分支中的英文 docs/，部署后可以换成自己的文档仓库。
部署到 Cloudflare
- 点击上方 Deploy to Cloudflare，按提示授权 GitHub，创建自己的模板仓库和 Worker。
- 确认构建命令为
pnpm run build、部署命令为pnpm run deploy，根目录为仓库根目录。 - 打开该 Worker 的 设置（Settings）→ 构建（Builds）→ 变量和机密（Variables and secrets），点击 添加，按下节填写需要修改的参数。
- 保存后，进入构建记录，对最新一次构建选择 重试构建（Retry build）。等待成功，再打开 Cloudflare 提供的
workers.dev地址。
以后更换文档源、站点地址、Logo 或 favicon 时，也在这个位置修改对应的值，保存后重新构建。
首次部署可能显示默认英文示例文档。如果控制台提示“未配置构建变量或密钥”，说明尚未添加参数，构建仍会读取模板默认值。复制模板不会自动把文档源改成你的仓库。
构建变量
以下 7 项都可以在 构建 → 变量和机密 中添加为普通变量。只填写需要修改的项，未添加的项沿用模板默认值。
添加时，名称和值填在各自的输入框中，值不加引号。例如名称填 DOCS_BRANCH，值填 main。
| 变量名称 | 默认值 | 如何填写 |
|---|---|---|
DOCS_REPO |
https://github.com/Azincc/nimbus-docs-template.git |
改成自己的文档仓库 HTTPS 地址，如 https://github.com/你的用户名/文档仓库.git |
DOCS_BRANCH |
main |
文档所在的分支名称 |
DOCS_PATH |
docs |
仓库里的文档文件夹；文档在仓库根目录时填 . |
DOCS_CONFIG_PATH |
docs/site.json |
仓库里的站点配置文件路径；没有此文件时添加变量并将值留空 |
SITE_URL |
https://nimbus.az1n.com |
改成自己的完整站点地址，如 https://你的Worker.你的子域.workers.dev；暂不确定时添加变量并将值留空 |
SITE_LOGO |
default |
可选；填 Logo 的 HTTP(S) 图片地址，或仓库里的图片文件路径 |
SITE_FAVICON |
default |
可选；填浏览器标签页图标的 HTTP(S) 图片地址，或仓库里的图片文件路径 |
默认的 docs/ 和 docs/site.json 对应英文示例。要部署当前中文文档，在同一构建变量区域同时添加：
| 变量名称 | 中文示例值 |
|---|---|
DOCS_PATH |
docs-zh-CN |
DOCS_CONFIG_PATH |
docs-zh-CN/site.json |
保留默认文档仓库和 main 分支，保存后重新构建。两项路径都相对文档源仓库根目录，选择中文不会改变模板代码来源。
“将值留空”是清空值的输入框，不要输入两个引号 ""。不添加变量会继承默认值；添加变量并留空，才会覆盖原来的默认值。
SITE_URL 用于搜索引擎等页面信息，不会绑定自定义域名。留空仍可访问网站，但不会生成依赖正式域名的 canonical 和 sitemap。
SITE_LOGO 和 SITE_FAVICON 默认填 default，沿用站点配置文件中的对应图片；未配置对应图片时使用模板内置的 Nimbus 官方 Logo。填图片 URL 或仓库路径时覆盖站点配置。Cloudflare 不接受空值时，直接填 default；空白值仍兼容相同的回退规则。使用仓库图片时，填写 docs-zh-CN/assets/nimbus-mark.svg 这样的路径，从文档仓库根目录算起。详见品牌资源。
旧部署请先更新模板，同步新版构建脚本和 public/nimbus-logo.svg，再将变量设为 default。
公开仓库不需要 DOCS_TOKEN。如果文档位于私有仓库，在同一个 构建 → 变量和机密 区域添加 DOCS_TOKEN，类型选择 Secret，填入仅授权目标仓库、具有 Contents: Read-only 权限的 GitHub Token。Token 仅在 Git 拉取期间使用，不能写入仓库文件或 URL。详见私有仓库部署。
这些参数需要设为 构建 变量，普通运行时变量不会自动提供给构建。保存参数后，选择 Retry build 才会更新网站。逐步操作见修改部署配置。
文档和模板在同一构建仓库、同一分支时，推送文档即可触发自动构建。使用独立文档仓库时，按原文档仓库构建挂钩连接自动更新。
本地运行
需要在电脑上开发模板时，准备 Git、Node.js 22.12.0 或更新版本，以及 pnpm 10.2.0，然后运行：
git clone https://github.com/Azincc/nimbus-docs-template.git
cd nimbus-docs-template
pnpm install --frozen-lockfile
pnpm dev也可以使用 npm：运行 npm ci 安装依赖，再运行 npm run dev。其他命令同样可将 pnpm <命令> 换为 npm run <命令>。
打开终端输出的本地地址即可浏览文档。开发命令会先拉取 GitHub 上的文档，因此首次运行需要网络连接。
pnpm dev 和 pnpm build 都从配置的远程仓库读取内容。直接修改本地 docs/ 或 docs-zh-CN/ 不会改变远程文档版本。要发布自己的内容，先将修改提交并推送到配置对应的仓库和分支，再重新构建。
构建与预览
pnpm build
pnpm preview:cf构建会依次拉取文档、转换 Markdown 和资源、校验站点配置，再生成静态页面和搜索索引。若本地链接缺失或站点配置无效，先修复源文件，再重新构建。
预览时，打开编写文档和站点配置，检查示例页面、相对链接和主题效果。页脚显示本次构建实际读取的文档提交 SHA。
确认构建产物后，可以运行 pnpm run deploy 发布到 Cloudflare，发布需要 Cloudflare 部署授权。部署命令只接受成功构建且未被修改的产物。修改站点后，要先重新执行 pnpm build。
开发模板时，使用 pnpm test 运行核心测试，构建后使用 pnpm check 检查 Astro 与 TypeScript（pnpm typecheck 为同义命令）。pnpm e2e:dev --port 8787 用于启动已构建产物，供浏览器测试访问。