mintlify__docs/zh/deploy/multi-repo.mdx

---
title: "多仓库部署"
description: "将多个 Git 仓库中的文件合并到一个 Mintlify 站点，并为每个源仓库分配独立的 URL 路径。"
keywords: ["multi-repo", "multiple repositories", "git sources", "URL path"]
---

<Info>
  多仓库部署在[企业版套餐](https://mintlify.com/pricing?ref=multi-repo)中可用。
</Info>

当一个站点需要来自多个 Git 仓库的内容时，请使用多仓库部署。当你为同一个 Mintlify 项目配置多个仓库作为源时，每个仓库的内容都会有自己的 URL 路径。

例如，你可以将产品文档、API 参考和 SDK 指南的独立仓库合并到一个站点中：

```text
docs.example.com/product
docs.example.com/api
docs.example.com/sdks
```

<div id="how-multi-repository-deployments-work">
  ## 多仓库部署的工作原理
</div>

多仓库部署中的每个仓库都有各自的：

- Git 提供方连接
- 分支
- 可选的内容目录
- URL 路径
- `docs.json`

在部署期间，Mintlify 会读取每个仓库并将已配置的源合并到一个站点中。每个源会显示在其配置的 URL 路径下。

其中一个仓库作为部署的**基础源**。其 `docs.json` 是根 `docs.json`，控制站点级配置，包括主题、颜色、Logo、站点名称、顶层导航、集成、SEO 以及其他顶层字段。其他每个源仅在其配置的 URL 路径下贡献各自的导航和内容。你配置的第一个仓库默认就是基础源，你可以随时[更改作为基础的源](#change-the-base-source)。

<Note>
  多仓库部署不同于[monorepo 配置](/zh/deploy/monorepo)。当你将所有内容与源代码一起存放在单个仓库的子目录中时，请使用 monorepo 配置。当你将内容分散存放在不同的仓库中时，请使用多仓库部署。
</Note>

<div id="requirements">
  ## 要求
</div>

- 企业版套餐
- 你的 Mintlify 项目的管理员权限
- 每个源仓库中都必须有 `docs.json` 文件
- 所有源仓库必须使用相同的 Git 提供方（全部为 GitHub 或全部为 GitLab）。添加来自不同提供方的源会移除所有现有的另一类型的源

<Warning>
  URL 路径必须唯一且不能重叠。例如，不要同时将一个源配置为 `/docs`，另一个源配置为 `/docs/api`。
</Warning>

<div id="configure-multiple-repositories">
  ## 配置多个仓库
</div>

<Steps>
  <Step title="打开 Git 设置">
    在仪表板中前往 [Git 设置](https://app.mintlify.com/settings/deployment/git-settings)。

    <Frame>
    <img src="/images/deployments/add-repository-light.png" alt="Mintlify 仪表板中的 Git 设置页面。底部可见 Add repository 按钮。" className="block dark:hidden" />
    <img src="/images/deployments/add-repository-dark.png" alt="Mintlify 仪表板中的 Git 设置页面。底部可见 Add repository 按钮。" className="hidden dark:block" />
    </Frame>
  </Step>

  <Step title="添加另一个仓库">
    点击 **Add repository**。
  </Step>

  <Step title="配置仓库源">
    选择仓库、分支以及所需的 Git 提供方特定字段（GitHub 或 GitLab）。
    
    <Frame>
    <img src="/images/deployments/repo-configuration-light.png" alt="Git 设置页面中的仓库配置面板。可见仓库、分支以及 GitHub 特定字段。" className="block dark:hidden" />
    <img src="/images/deployments/repo-configuration-dark.png" alt="Git 设置页面中的仓库配置面板。可见仓库、分支以及 GitHub 特定字段。" className="hidden dark:block" />
    </Frame>

    对于 GitHub 源，Mintlify GitHub App 必须能够访问该仓库。对于 GitLab 源，请提供项目 ID 以及具有 `read_repository` 权限的部署令牌。

    如果仓库的 `docs.json` 位于子目录而非根目录中，请启用 **docs.json is in a subdirectory** 并输入指向该目录的路径。
  </Step>

  <Step title="设置 URL 路径">
    为仓库源输入一个 **URL path**。

    URL 路径决定了来自该仓库的内容在你的文档站点中显示的位置。例如，URL 路径为 `api` 时，内容会在 `docs.example.com/api` 下提供。

    <Note>
      你可以使用或不使用前导斜杠输入路径。Mintlify 在保存时会自动规范化该值。
    </Note>
  </Step>

  <Step title="保存更改">
    点击 **Save changes**。Mintlify 会保存配置，并将合并后的站点的部署排入队列。
  </Step>
</Steps>

<div id="change-the-base-source">
  ## 更改基础源
</div>

基础源为你的多仓库部署提供站点级配置。当你希望由另一个仓库的 `docs.json` 控制主题、颜色、站点名称和顶层导航等设置时，请更改基础源。

<Steps>
  <Step title="打开 Git 设置">
    在你的控制台中前往 [Git 设置](https://app.mintlify.com/settings/deployment/git-settings)。

    当前的基础源会在仓库名称旁显示 **Base** 徽章。
  </Step>

  <Step title="设置新的基础源">
    在你想用作基础的仓库上，选择 **Set as base**。

    Mintlify 会立即更新基础源，并使用新基础仓库的 `docs.json` 作为站点级配置来排队进行一次部署。
  </Step>
</Steps>

<Warning>
  更改基础源会用新基础仓库 `docs.json` 中的值替换站点级设置，例如主题、颜色、Logo、站点名称和顶层导航。其他源的 URL 路径和内容不受影响。
</Warning>

<div id="example-repository-layout">
  ## 示例仓库布局
</div>

在此示例中，每个源都有自己的仓库以及自己的 `docs.json`。

```text
acme/product-docs
├── docs.json
├── overview.mdx
└── guides/

acme/api-docs
├── docs.json
├── introduction.mdx
└── reference/

acme/sdk-docs
├── docs.json
├── quickstart.mdx
└── javascript/
```

为每个仓库配置一个 URL 路径：

| 仓库 | URL 路径 | 发布路径 |
| --- | --- | --- |
| `acme/product-docs` | `product` | `/product` |
| `acme/api-docs` | `api` | `/api` |
| `acme/sdk-docs` | `sdks` | `/sdks` |

<div id="navigation-behavior">
  ## 导航行为
</div>

Mintlify 会将每个仓库的导航合并到一个站点导航中。每个仓库源都会成为配置的 URL 路径下的一个顶级产品分区。

每个产品分区的名称来自对应仓库的 `docs.json` 中的 `name` 字段。例如，如果某个仓库的 `docs.json` 设置了 `"name": "API Reference"`，则其产品分区会在合并后的导航中显示为 "API Reference"。

请将每个源的导航限定在其自身的仓库范围内。例如，API 仓库中的页面应仅引用位于 API 仓库中的文件。同样地，SDK 仓库中的页面应仅引用位于 SDK 仓库中的文件。

源仓库内部不支持嵌套的 `navigation.products` 配置。

<div id="link-between-sources">
  ### 在不同源之间创建链接
</div>

相对 Markdown 链接无法跨仓库解析，因为每个源在构建时只能看到自身的文件。要从某个源链接到另一个源中的页面，请使用包含目标源 URL 路径的根相对 URL 路径：

```mdx
See the [API reference](/api/reference/authentication) for details.
```

在此示例中，`/api` 是为 API 仓库源配置的 URL 路径。该链接会在已发布站点层面解析为 `docs.example.com/api/reference/authentication`。

不要对内部跨源链接使用完整的 `https://` URL — 根相对路径可保证预览和自定义域名正常工作。

<div id="reference-navigation-from-another-source">
  ## 从其他源引用导航
</div>

使用 `sourceRef` 可将另一个仓库的导航放置到基础源 `docs.json` 中的特定位置。如果未使用 `sourceRef`，Mintlify 会将每个仓库作为独立的顶层产品分区添加。

<div id="requirements">
  ### 要求
</div>

- 被引用的仓库必须已配置为同一多仓库部署中的源。
- `sourceRef` 的值必须使用 `owner/repo` 格式。不支持仅使用挂载路径或仓库名称。
- 被引用的源必须定义与主源相似的导航结构。例如，在 `anchors` 中使用 `sourceRef` 时，被引用的源必须定义 `navigation.anchors`。
- `sourceRef` 条目不能形成循环。源不能引用自身，两个源也不能相互引用。
- `sourceRef` 必须出现在导航数组中。它在 `navigation` 的顶层无效。

<div id="usage">
  ### 用法
</div>

在基础源的 `docs.json` 的导航数组中添加一个 `sourceRef` 条目。其值必须是仓库的 `owner/repo` 标识符。

```json
{ "sourceRef": "acme/api-docs" }
```

Mintlify 支持在 `anchors`、`tabs`、`groups`、`pages`、`products` 以及 `navigation.global` 下的数组中使用 `sourceRef`。

例如，若要将多个仓库的 anchors 合并到单个 anchor 导航中：

```json
{
  "navigation": {
    "anchors": [
      {
        "anchor": "Guides",
        "pages": ["quickstart"]
      },
      {
        "sourceRef": "acme/api-docs"
      }
    ]
  }
}
```

如果 `acme/api-docs` 定义了自己的 `navigation.anchors`，Mintlify 会用这些 anchors 替换 `sourceRef` 条目，并在其路径前加上被引用源的 URL 路径前缀。

<div id="removing-a-repository-source">
  ## 移除仓库源
</div>

你可以从仪表板的 [Git 设置页面](https://app.mintlify.com/settings/deployment/git-settings)移除仓库源。当只剩一个仓库源时，Mintlify 会移除该源的 URL 路径，并将剩余的仓库作为部署的根源。