---
title: "修改部署配置"
description: "不用编写代码，直接在 Cloudflare 控制台填写文档源、站点地址和图片参数，保存后重新构建。"
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus.az1n.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 修改部署配置

文档仓库、分支、目录、站点地址和图片都可以在 Cloudflare 控制台中设置。日常调整这些参数，无需安装开发工具，也不用编辑代码或 JSON 文件。

操作顺序：**打开构建设置 → 添加或修改变量 → 保存 → 重新构建**。

## 1. 找到构建变量入口

1. 登录 Cloudflare，进入 **Workers 和 Pages**。
2. 点击你部署的 Worker。
3. 打开 **设置（Settings）**，向下找到 **构建（Builds）**。
4. 在构建区域找到 **变量和机密（Build variables and secrets）**，点击该区域的 **添加**。

请使用“构建”下面的变量入口。页面上方的“运行时变量和机密”是运行时设置。本模板是静态网站，该区域可能提示“不能将变量添加到只有静态资产的 Worker”，但不影响下方的构建变量。

如果显示“未配置构建变量或密钥”，说明网站正在使用模板自带的默认值，不代表部署失败。直接点击“添加”即可；常用参数添加后，就能在列表中修改。

## 2. 填写基础参数

点击“添加”后，会出现 **类型、名称、值** 三个输入项：

* **类型**：以下公开参数都选 **变量（Variable）**。
* **名称**：从下表复制英文名称，大小写保持一致。
* **值**：填写自己的内容，不加引号。名称和值分开填，不要把 `DOCS_BRANCH=main` 整行填到一个输入框。

每填完一项，点击“添加”继续填写下一项。首次设置时，建议添加下面五项，便于以后集中管理。如果某项默认值仍适用，也可以不添加。

| 想修改什么            | 名称                 | 值怎么填                                                                          |
| ---------------- | ------------------ | ----------------------------------------------------------------------------- |
| 文档放在哪个 GitHub 仓库 | `DOCS_REPO`        | 仓库的 HTTPS 地址，例如 `https://github.com/example-user/project-docs.git`；将示例换成自己的仓库 |
| 使用哪个分支           | `DOCS_BRANCH`      | 例如 `main`；填写文档所在的实际分支                                                         |
| 使用哪个文件夹          | `DOCS_PATH`        | 例如 `docs`；文档就在仓库最外层时填一个英文句点 `.`                                               |
| 站点配置文件在哪里        | `DOCS_CONFIG_PATH` | 仓库中有该文件时填 `docs/site.json`；没有配置文件时保留这一项，把值输入框留空                               |
| 网站的访问地址          | `SITE_URL`         | 例如 `https://你的Worker.你的子域.workers.dev`，或已绑定的自定义域名；包含 `https://`，不附带页面路径       |

`example-user/project-docs` 只是格式示例，填写时请换成自己的仓库。在 GitHub 打开文档仓库，点击 **Code → HTTPS** 复制地址，分支名可以在文件列表上方查看。默认文档源为 `https://github.com/Azincc/nimbus-docs-template.git`，复制模板不会自动将它改成你的仓库。

文件夹和配置文件路径都相对于文档仓库的根目录。例如文档在 `manual` 文件夹，配置文件在 `config/site.json`，就分别填写这两个值，前面不加仓库地址。

模板默认的 `DOCS_PATH=docs` 和 `DOCS_CONFIG_PATH=docs/site.json` 读取英文示例。切换到本仓库的完整中文示例时，保留默认文档仓库和分支，将这两项分别改为 `docs-zh-CN` 和 `docs-zh-CN/site.json`，保存后重新构建。使用其他文档仓库时，以那个仓库的实际路径为准。

**在 Cloudflare 输入框里，“留空”就是不输入任何字符，不要输入两个引号 `""`。** 新文档仓库没有站点配置文件时，要添加 `DOCS_CONFIG_PATH` 并将值留空；仅省略这一项会继续使用模板默认的 `docs/site.json`。

`SITE_URL` 默认为示例站点 `https://nimbus.az1n.com`，部署时请改成自己的实际访问地址。暂时不确定地址时，可以留空：网站仍可浏览，但不会生成依赖正式地址的搜索引擎链接和站点地图。使用自定义域名前，需要先在 Worker 的“域”页面完成配置；仅填写地址不会自动绑定域名。

## 3. 按需设置 Logo 和浏览器图标

当前模板版本支持以下两个普通变量，默认值均为 `default`。它们沿用站点配置中的对应图片；未配置对应图片时，使用模板内置的 Nimbus 官方 Logo。

| 想修改什么      | 名称             | 值怎么填                                                             |
| ---------- | -------------- | ---------------------------------------------------------------- |
| 网站 Logo    | `SITE_LOGO`    | `default`、图片的 HTTP(S) 地址或文档仓库内的图片路径，例如 `docs/assets/logo.svg`    |
| 浏览器标签页的小图标 | `SITE_FAVICON` | `default`、图片的 HTTP(S) 地址或文档仓库内的图片路径，例如 `docs/assets/favicon.png` |

图片地址必须指向图片本身，不能使用 GitHub 的文件预览页面地址。图片放在文档仓库时，填写相对于仓库根目录的文件路径即可。

这两项独立生效，修改 Logo 不会同时改变浏览器图标。填图片 URL 或仓库路径会覆盖站点配置，改回 `default` 即可恢复上述回退规则。Cloudflare 不接受空值时，直接填 `default`；空白值仍兼容相同的规则。

旧部署请先[更新模板](/deployment/template-update)，同步新版构建脚本和 `public/nimbus-logo.svg`，再将变量设为 `default`。

## 4. 私有仓库再添加机密

公开仓库无需添加机密。使用私有文档仓库时，单独添加以下机密：

| 类型             | 名称           | 值                                      |
| -------------- | ------------ | -------------------------------------- |
| **机密（Secret）** | `DOCS_TOKEN` | 仅授权目标仓库、具有 Contents 只读权限的 GitHub Token |

Token 的创建方法见[私有仓库部署](/deployment/private-repository)。直接把 Token 填到 Cloudflare 的机密输入框，不要填进仓库地址、普通变量、文档或代码文件。

## 5. 保存并重新构建

1. 检查刚填写的名称和值，点击页面底部的 **保存（Save）**。
2. 等待保存请求完成。若仍提示“未保存的更改”，先检查有无错误提示。没有错误时，刷新设置页；刚填写的变量和值仍在，就表示保存成功。
3. 打开 **部署（Deployments）**，进入构建记录，选择 **重试构建（Retry build）**。
4. 等待构建和部署成功，再打开网站查看结果。

变量保存后，需要重新构建才会改变已发布的静态页面。只修改这些参数时，无需重新复制模板、再次点击部署按钮，也不用修改构建命令、部署命令或根目录。

如果构建失败，查看日志中的错误并修正对应输入，再重试。例如“配置文件不存在”通常是 `DOCS_CONFIG_PATH` 没有指向真实文件；没有该文件时将值留空。

## 以后如何修改或恢复默认值

再次打开 **设置 → 构建 → 变量和机密**，修改列表中对应的值，保存后重新构建即可。

已保存的构建变量优先于模板文件中的默认值。以后模板更新默认值时，也会继续使用你保存的配置。

要恢复模板默认值，删除对应构建变量，保存后重新构建。保留变量时，也可以按下表调整：

| 操作                                                  | 生效结果                                 |
| --------------------------------------------------- | ------------------------------------ |
| 删除变量                                                | 重新读取模板的默认值                           |
| 将 `DOCS_CONFIG_PATH` 的值留空                           | 使用通用站点配置，不读取站点 JSON                  |
| 将 `SITE_URL` 的值留空                                   | 不指定正式站点地址                            |
| 将 `SITE_LOGO` 或 `SITE_FAVICON` 改为 `default`（空白值也兼容） | 沿用站点配置中的对应图片；未配置时使用内置 Nimbus 官方 Logo |

## 常见问题

| 遇到的情况        | 处理方法                                                |
| ------------ | --------------------------------------------------- |
| 找不到添加按钮      | 向下找到“构建”区域中的“变量和机密”，不要停留在页面上方的运行时变量区域               |
| 保存后还是提示未保存   | 等待保存请求完成并检查错误提示；无错误时刷新页面，核对变量和值是否仍在，提示可能未及时更新       |
| 仍然显示模板示例文档   | 将 `DOCS_REPO` 改为自己的文档仓库，保存并重新构建                     |
| 找不到站点配置文件    | 有文件时核对路径；没有文件时保留 `DOCS_CONFIG_PATH` 并把值留空           |
| 私有仓库无法拉取     | 确认 `DOCS_TOKEN` 类型为机密，且 Token 有目标仓库的读取权限            |
| Logo 或图标没变化  | 检查图片地址、保存状态和构建结果；旧部署先按上文更新模板                        |
| 文档仓库更新后网站没变化 | 为独立文档源设置[构建挂钩](/deployment/deploy-hook)，让文档推送自动触发构建 |

站点名称、导航、主题和侧栏顺序的设置方法见[站点配置](/site-config)与[侧栏顺序](/sidebar-order)。构建变量只支持本文列出的参数，并非所有站点设置都能通过控制台表单修改。

## 供模板维护者参考

公开默认值保存在部署关联的模板仓库中，位于根目录 `wrangler.jsonc` 的 `vars` 字段。构建脚本先读取构建环境中的同名变量，未设置时才读取默认值。`DOCS_TOKEN` 只从构建环境读取。

仓库默认值不会自动出现在 Cloudflare 的构建变量列表。为新用户准备这个列表时，在构建设置中添加一次即可。文档源、分支、目录和站点地址填写后，用户就能直接在 Cloudflare 中完成日常调整。

维护者也可以修改并提交仓库中的默认值，但已保存的同名构建变量仍然优先。修改后，需要构建包含这些改动的新模板提交；重试旧提交不会读到新改动。

官方参考：[Workers Builds 配置](https://developers.cloudflare.com/workers/ci-cd/builds/configuration/)。

Source: https://nimbus.az1n.com/deployment/configuration/index.mdx