mintlify__docs/zh/editor/branching-and-publishing.mdx

---
title: "分支与发布"
description: "了解分支及保护规则如何决定发布时所发生的操作，以及如何管理完整的审查与部署工作流。"
keywords: ["编辑器", "分支", "发布", "拉取请求", "预览", "git", "合并", "部署"]
---

Web 编辑器会在你输入时自动保存所有内容，但你的更改只有在你选择发布后才会上线。

发布时所发生的具体操作取决于两件事：**你当前所在的分支**，以及**该分支是否要求拉取请求**。

<div id="saving-versus-publishing">
  ## 保存与发布
</div>

**保存**会自动进行。Mintlify 会将你的编辑存储在其服务器上，并在浏览器标签页、设备以及网络中断之间保留这些内容。

**发布**会将你的更改提交到你的 Git 存储库。点击工具栏中的 **Publish** 以打开发布菜单，将你的更改保存为一次 Git 提交，并创建一个拉取请求。

编辑器会将以下内容作为待处理的更改进行跟踪：

- 页面中的内容编辑
- 新建或删除的页面
- 导航结构的更改
- 媒体上传
- 配置更新

<div id="what-happens-when-you-publish">
  ## 发布时会发生什么
</div>

点击发布按钮后可用的操作取决于你当前所在的分支，以及该分支是否设置了要求拉取请求的分支保护规则。

| 分支类型 | 分支保护 | 可用操作 |
|-------------|-------------------|-------------------|
| <Tooltip headline="部署用分支" tip="用于发布到线上文档站点的分支，通常为 'main'。">部署用分支</Tooltip> | 无 | **Publish** 直接发布到你的线上站点 |
| 部署用分支 | 需要拉取请求 | **Create branch** 将更改转移到新分支 |
| <Tooltip headline="功能分支" tip="一个隔离的分支，你会在其中进行更新，然后再合并到部署用分支。">功能分支</Tooltip> | 无 | **Save in branch**、**Create pull request** |
| 功能分支 | 需要拉取请求 | **Save in branch**、**Create pull request** |

- **Publish**：立即将你的更改提交并部署到线上站点。
- **Save in branch**：将更改提交到功能分支，但不合并到部署用分支。
- **Create branch**：当你在受保护的部署用分支上时，将待处理的更改转移到一个新的功能分支。
- **Create pull request**：打开一个以你的部署用分支为目标的拉取请求。

如果没有待处理的更改，编辑器会禁用发布和保存操作。

<Note>
  在 Mintlify 构建并部署你的更改后，你的线上站点会更新。这通常需要 30 秒到几分钟。请在你的 [dashboard](https://app.mintlify.com) 上查看部署状态。
</Note>

<div id="when-to-use-a-branch">
  ## 何时使用分支
</div>

如果你不使用基于 Git 的工作流，请**直接在部署用分支上编辑**。

当你使用基于分支的工作流，且每次更改都在单独的分支上进行时，请**创建一个分支**。

<div id="create-and-switch-branches">
  ## 创建和切换分支
</div>

<div id="create-a-branch">
  ### 创建分支
</div>

1. 点击编辑器工具栏中的分支名称。
1. 点击 **Create new branch**。
1. 如果你有待处理的更改，选择是将它们带到新分支，还是留在当前分支上。
1. 输入名称并点击 **Create branch**。

<Tip>
  使用具有描述性的分支名称，这样你能轻松识别它们，其他人也能理解每个分支的用途。
</Tip>

<div id="switch-branches">
  ### 切换分支
</div>

1. 点击工具栏中的分支名称。
1. 搜索或滚动到你想要的分支。
1. 点击分支以切换到该分支。

<Note>
  在你有未发布更改时切换分支，编辑器会提示你将这些更改带到新分支，或者将它们留下。留下的更改会保留在原始分支上。
</Note>

<Tip>
  要复制分支名称，将鼠标悬停在下拉菜单中的分支上并点击复制图标。在与团队成员共享分支或在拉取请求中引用它时，这会很有用。
</Tip>

<div id="preview-your-changes">
  ## 预览你的更改
</div>

每次你将更改保存到功能分支时，Mintlify 会构建一个预览部署——一个临时 URL，你的更改会在那里以发布后完全相同的样子呈现。

<div id="access-and-share-a-preview">
  ### 访问并分享预览
</div>

1. 点击编辑器工具栏中的 **Publish**。
1. 在发布菜单中，点击预览 URL。URL 格式为 `organization-branch-name.mintlify.site`。
    <Frame>
      <img src="/images/editor/preview-url-light.png" alt="发布菜单中突出显示的预览 URL。" className="block dark:hidden" />
      <img src="/images/editor/preview-url-dark.png" alt="发布菜单中突出显示的预览 URL。" className="hidden dark:block" />
    </Frame>

复制该 URL 并发送给审查者。每次保存到该分支时，预览都会自动更新。

<div id="restrict-access-to-previews">
  ### 限制对预览的访问
</div>

预览 URL 默认是公开可访问的。要将访问限制为你的 Mintlify 组织成员，请在控制台的 [Add-ons](https://app.mintlify.com/products/addons) 页面中启用预览身份验证。

<div id="share-editor-links">
  ### 分享编辑器链接
</div>

要邀请团队成员到某个分支上的特定页面，请从你的浏览器地址栏复制 URL 并分享出去。任何有权限访问你的 Mintlify 组织的人都可以直接在他们的编辑器会话中打开该链接。

URL 格式为：

```text
https://app.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}
```

例如：`https://app.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx`

<div id="review-and-merge-pull-requests">
  ## 审查并合并拉取请求
</div>

当当前分支有打开的拉取请求时，发布菜单会显示一个审查面板，其中包含：

- 拉取请求的标题、描述以及是否为草稿。
- 源分支和目标分支。
- 更改的文件数量。
- 部署用分支上的审批要求：**Approval required**、**Code owner required** 或无要求。
- 当前的审查状态：**Approved**、**Changes requested** 或 **Awaiting review**。

点击 **Open in GitHub** 或 **Open in GitLab** 可在你的 Git 服务提供商中查看拉取请求。

在审查者批准拉取请求后，点击 **Merge and publish** 可直接从编辑器中合并并部署。编辑器会在合并后切换到你的部署用分支。

<div id="approve-pull-requests-from-the-editor">
  ### 在编辑器中批准拉取请求
</div>

对于 GitHub 存储库，审查者可以在编辑器中批准打开的拉取请求。当有打开的拉取请求时，如果你的账户具有审查权限，审查面板中会出现 **Approve pull request** 按钮。当更改可以合并时，点击 **Approve pull request**。审查状态会更新为 **Approved**，并且 **Merge and publish** 操作将变为可用。

对于草稿拉取请求、你已批准的拉取请求或 GitLab 合并请求，批准操作不可用。点击 **Open in GitLab** 可在 GitLab 中批准合并请求。

<Tip>
  在你的 Git 服务提供商中配置分支保护规则以要求拉取请求。请参阅 GitHub 文档中的 [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) 或 GitLab 文档中的 [Protected branches](https://docs.gitlab.com/user/project/repository/branches/protected/)。
</Tip>

<div id="review-changes-before-merging">
  ### 在合并前审查更改
</div>

点击发布菜单中任何已更改的文件，即可在差异视图中打开它，并将你的分支与已发布版本进行比较。在可视化模式下，你会看到可视化差异；在源代码模式下，你会看到文本差异。无法显示差异的文件（如图片或已删除的文件）会出现在列表中，但不可点击。

文件树会高亮显示已变更的页面，让你一眼就能看出 [automation](/zh/automations) 或团队成员改动了哪些文件。出现在分支差异中的未列出页面，即使它们不在站点导航中，也可以从发布菜单中打开。

<div id="open-an-automation-run-in-the-editor">
  ### 在编辑器中打开自动化运行
</div>

当 [automation](/zh/automations) 打开一个拉取请求时，你可以直接从运行审查 UI 或其 Slack 通知跳转到编辑器，并切换到该自动化的分支：

- 在控制台的 **Automation Runs** 页面中，点击已完成运行上的 **Open in editor**。
- 在 Slack 通知中，点击 **View changes** 链接。

任一入口都会打开编辑器并切换到该自动化的分支，发布菜单中会预选已变更的页面。你无需离开编辑器即可审查差异并合并或请求更改。

<div id="simultaneous-publishing">
  ### 同时发布
</div>

每个分支同一时刻只能有一次发布。如果另一位团队成员正在向同一分支发布，请等待当前发布完成后再重试。

<div id="pull-request-titles-and-descriptions">
  ### Pull request 标题和描述
</div>

如果你的组织要求使用 pull request，你可以在发布时输入标题和描述。如果其中任一项留空，编辑器会使用默认信息，其中列出你创建、更新、移动或删除的文件。

<div id="resolve-conflicts">
  ## 解决冲突
</div>

当你的分支和部署用分支对同一文件有不兼容的更改时，就会发生冲突。例如，你和团队成员编辑了同一文件中的同一行，或将文件移动到了不同位置。

当冲突阻止发布时，编辑器会显示警告。按照提示选择保留每个冲突部分中的哪个版本。

<div id="collaborate-in-real-time">
  ## 实时协作
</div>

当多人在同一分支上打开同一页面时，他们会实时一起编辑。每个人的光标和编辑对所有人都可见，并在工具栏中显示头像。

- 来自所有协作者的更改会自动合并。两个人编辑同一部分不会产生冲突。
- 撤销只会影响你自己的编辑。
- 如果你的连接断开，编辑会在本地保存，并在重新连接时同步。

当 [Mintlify agent](/zh/agent) 通过 API 或 MCP 编辑页面时，它会像任何其他协作者一样出现在编辑器中。你会在工具栏中看到该代理的头像，并在其最近编辑位置看到一个实时光标。代理完成后，光标会自动消失。

<div id="git-sync">
  ## Git 同步
</div>

当有人从编辑器之外向你的存储库推送更改时，编辑器会自动合并这些更改。

不重叠的更改会自动应用。如果远程更改和你的本地编辑影响了页面的同一部分，编辑器会高亮该冲突，以便你解决它。

<div id="commit-signing">
  ## 提交签名
</div>

在你的[账户设置](https://app.mintlify.com/settings/account)中授权你的 GitHub 账号，即可用该账号对提交进行签名。若未完成授权，则由 Mintlify GitHub 应用对在 Web 编辑器中完成的提交进行签名。

有关编辑器操作如何映射到 Git 操作的参考，请参阅 [Git 基础](/zh/editor/git-essentials#how-the-editor-maps-to-git)。