Cloudflare Docs 是开源的,托管在 GitHub 上的 cloudflare-docs 仓库 ↗。这意味着任何人,包括非 Cloudflare 组织的成员,都可以对文档做出贡献。我们欢迎所有有助于保持文档高质量和最新状态的建议。
要对我们的文档做出贡献,您需要在 GitHub 上创建一个账户 ↗(如果您还没有的话)并登录。然后您有以下三个选择:
- GitHub issue:快速提交常规建议。
- 快速编辑(编辑按钮):快速创建 pull request。如果您想在 Web 浏览器中编辑单个页面且不需要预览更改,这是最佳选择。
- 完整开发:创建 pull request。如果您想编辑多个页面并预览更改,这是最佳选择。这可以在您的 Web 浏览器中(使用 Codespaces ↗)或在您的本地计算机上(使用 Visual Studio Code ↗)进行。
除了使用 Cloudflare 风格指南 获取语法和风格指导外,我们还建议浏览我们的组件,以添加按钮、标签页和可折叠部分等其他格式。
要创建 GitHub issue:
- 登录 GitHub ↗ 并前往 cloudflare-docs 仓库 ↗。
- 选择 Issues,然后选择 New issue。
- 选择 issue 类型,填写表单,然后选择 Create。
要使用编辑按钮快速创建 pull request:
-
前往 Cloudflare Docs 中您要编辑的页面
选择
页面的 Markdown 将会打开。
Cloudflare Docs 中的每个页面(包括此页面)在右侧边栏都有一个 Edit 按钮,在页面最底部有一个 Edit page 按钮。Edit 或 Edit page

-
进行编辑并选择 Commit changes。
-
在表单中,更新 Commit message,在方括号中注明您更改的产品,并简要描述您的更改。例如 “[Images] Fixed broken link."
-
更新 Extended description,提供有关您更改了什么以及原因的更多详细信息。细节越详细越好。
-
依次选择 Propose changes > Create pull request > 再次选择 Create pull request。
要通过完整开发工作流 ↗进行编辑并创建 pull request:
-
如果您在 Web 浏览器中编辑(使用 Codespaces ↗),请转到步骤 3。
如果您在本地计算机上编辑(使用 Visual Studio Code ↗):
- (必须)安装 Node.js ↗(版本 24 或更高版本)。
- (推荐但非必须)安装 Vite+ ↗,并使用
vp env↗ 管理 Node.js 和包管理器版本。 - (必须)将 fork 克隆到您的本地计算机。 ↗
-
从您的 fork(或克隆)创建一个分支。
-
进行编辑。
-
通过安装依赖并启动本地开发服务器来预览您的编辑:
pnpm install pnpm run dev终端中会出现一个链接,例如
https://localhost:1111/,您可以在此处预览更改。预览会随着您的编辑自动更新。 -
提交您的更改。
-
将您的 commit 推送到您的分支,然后推送到您的 fork。
-
返回 GitHub 并根据您提交的更改创建 pull request。在描述表单中,在方括号中加入您更改的产品,并简要描述您的更改。例如,“[Images] Fixed broken link.”
在您创建 issue 或 PR 后,Cloudflare 组织的成员将审核您的建议。以下是后续流程:
- Cloudflare 组织的成员可能会标记其他人进行技术或内容审核,或者提供反馈。
- 如果您的建议需要更多信息,Cloudflare 组织的成员可能会通过评论提出后续或澄清问题。如果他们添加了
more-information-needed标签,且您在 14 天内未做出回应,该 issue 或 pull request 将自动关闭。 - 如果您的更改被批准:
- 对于 GitHub issue,Cloudflare 成员可能会创建并链接一个解决您请求的新 pull request。当他们合并 PR 时,也将关闭您的 issue。
- 对于 GitHub PR,Cloudflare 成员将合并您的 PR。
- 如果您的建议未被批准,Cloudflare 成员将说明原因并关闭您的 issue 或 PR。
感谢您为我们的开源生态系统做出贡献,并成为 Cloudflare 社区的一员。
我们在 GitHub ↗ 中工作(也很乐意这样做),但它绝不是完美的工具。
我们添加了若干易用性改进,以帮助分诊收到的工作、简化审核,并自动沟通。
为帮助作者分诊工作(并辅助后台报告),我们会自动添加若干标签,并分配 issue / pull request。
对于 pull request,我们使用特定的 GitHub action ↗ 来添加标签并分配 codeowners。
- Label products ↗:我们会为顶级产品文件夹添加标签,帮助作者扫视收到的 pull request,并判断哪些与自己相关。
- Label size ↗:我们会为 pull request 的规模添加标签,帮助作者了解差异的相对大小。这不是完美的度量,但我们会用变更行数来估算 pull request 的规模:
- Assign codeowners ↗:我们使用 CODEOWNERS ↗ 文件,根据变更的文件自动把人分配到 pull request。这种分配帮助作者筛选并找出与自己相关的 pull request。
对于 issue,我们使用类似的 GitHub action ↗ 来添加标签并分配 codeowners。
我们的脚本 ↗会单独处理 issue,因为它们通常包含指向站点的链接,而不是仓库内的文件。我们会提取 issue 描述字段中的相关链接,然后据此分配作者(同样基于 CODEOWNERS)并添加产品标签。
为简化审核,我们使用若干自动化来帮助解决常见的审核问题。
每次 commit 都会运行一项必需检查:CI ↗。
该检查会确保:
我们经常收到关于批准的问题,尤其是触及多个产品领域(或我们的组件)的 pull request。
对于打开的 pull request,Cloudflare Docs Bot 会发布一条 Review coverage ↗ 评论,说明哪些区域仍需 CODEOWNERS 批准、建议这些区域的联系人,并汇总已经覆盖的区域。展开 CODEOWNERS mappings 部分,可查看评论中显示的所有权区域对应的精确模式和所有者。该 bot 会跳过草稿、已关闭以及 spam/off-topic 的 pull request。
我们使用一个 GitHub action ↗,为 pull request 上的每次 commit 发布预览构建(并在 pull request 上评论这些链接 ↗)。此操作确保审核者能够看到站点和内容渲染后的实际效果(而不仅仅是在 GitHub 中查看变更的 Markdown)。
我们正在迁移到 Workers Builds,它原生提供该功能。
根据反馈,我们还添加了 before/after 链接表,帮助审核者在预览构建中轻松找到链接。
当 pull request 重命名或删除内容文件路径时,潜在重定向很难检查。
我们有一个专门的 action ↗,会发布评论,帮助审核者识别并检查这些路径。
我们主要通过 no-response ↗ GitHub Action 自动沟通。
开源意味着我们接受任何人提交的 issue 和 pull request。其中很多要么不言自明,要么有足够的上下文供我们跟进。
但那些上下文不足的 issue 往往很痛苦(尤其是在我们这样繁忙的仓库 ↗中)。作者必须询问更多细节,然后记得回头查看,有时还要再次追问,然后再检查一次。
为减少这类心理负担,我们会提出问题,然后应用 more-information-needed 标签。该标签会启动一个 14 天倒计时 ↗,等待作者回复。如果他们回复了,标签会被移除,对话可以继续。如果他们没有回复,issue 会自动关闭,并附带一条解释原因的评论 ↗。
我们希望这个工作流能在团队需求与对贡献者的尊重之间取得平衡。
我们有意避免使用会在一段时间无活动后关闭 pull request 或 issue 的 stale 工作流 ↗。
在我们看来,这个工作流带来的摩擦和挫败多于它解决的问题。某件事存在了一年,并不意味着它不再相关。
cloudflare-docs 仓库包含一个 AGENTS.md ↗ 文件,它能帮助 AI 编码代理(coding agent)理解仓库的结构、工具和约定,以便他们在为文档做出贡献时进行正确且可构建的更改。
AGENTS.md ↗ 是一种用于引导编码代理的简单、开放的格式。
该仓库开箱即用地包含了以下 AI 工具的配置:
- OpenCode ↗
- Windsurf ↗
- Claude Code ↗
- Gemini CLI ↗
- GitHub Copilot ↗(通过 VS Code)
Agent 的技能、命令和 agent 定义都保存在 .agents/ 中,并会自动符号链接到每个工具的预期位置。