> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装 CLI

> 使用命令行界面（CLI）在本地预览文档、实时测试更改，并在部署文档站点之前发现问题。

<img className="block dark:hidden my-0 pointer-events-none" src="https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/installation/local-development-light.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=923b23e1a0c8f22009b1876dc3dee86d" alt="用于表示 CLI 的装饰性图形。" width="1184" height="320" data-path="images/installation/local-development-light.png" />

<img className="hidden dark:block my-0 pointer-events-none" src="https://mintcdn.com/anotherhorizon/nGGkQ8HPtMLIJ_OO/images/installation/local-development-dark.png?fit=max&auto=format&n=nGGkQ8HPtMLIJ_OO&q=85&s=80ca9c1b30c8708c0057f439dc6e8434" alt="用于表示 CLI 的装饰性图形。" width="1184" height="320" data-path="images/installation/local-development-dark.png" />

使用 [CLI](https://www.npmjs.com/package/mint) 在撰写和编辑时本地预览文档。上线前即可实时查看更改、测试文档站点的外观与功能，并及时发现断链或无障碍问题等故障。

CLI 还提供维护文档的实用工具，包括用于重命名文件、验证 OpenAPI 规范以及在不同格式之间迁移 content 的命令。

<div id="prerequisites">
  ## 前提条件
</div>

* 已安装 [Node.js](https://nodejs.org/en) v20.17.0 及以上版本（推荐使用 LTS 版本）
* 已安装 [Git](https://git-scm.com/downloads)
* 已将你的文档存储库克隆到本地

<div id="clone-your-repository">
  ### 克隆你的存储库
</div>

<Steps>
  <Step title="定位你的存储库">
    1. 前往控制台中的 [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 页面。
    2. 记下你的存储库位置。它会是以下格式之一：

    * `mintlify-community/docs-{org-name}-{id}`（Mintlify 托管的存储库）
    * `your-org/your-repo`（你自己的 GitHub 存储库）
  </Step>

  <Step title="克隆你的存储库">
    <Tabs>
      <Tab title="你自己的存储库">
        将 `your-org/your-repo` 替换为你在 [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 中看到的实际存储库信息。

        ```bash theme={null}
        git clone https://github.com/your-org/your-repo
        cd your-repo
        ```

        <Tip>
          **需要 GitHub App。** 若要在你推送更改时启用自动部署，必须安装 GitHub 应用。更多信息请参见 [GitHub](/zh/deploy/github)。
        </Tip>
      </Tab>

      <Tab title="Mintlify 托管的存储库">
        你可以将存储库克隆为私有或公开存储库。公开存储库对所有访问该存储库 URL 的人可见，私有存储库仅对你所在组织中的成员可见。

        在控制台的 [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 页面，选择 **Clone as private** 或 **Clone as public**。
      </Tab>
    </Tabs>
  </Step>
</Steps>

<div id="install-the-cli">
  ## 安装 CLI
</div>

运行以下命令来安装 CLI：

<CodeGroup>
  ```bash npm theme={null}
  npm i -g mint
  ```

  ```bash pnpm theme={null}
  pnpm add -g mint
  ```
</CodeGroup>

<div id="preview-locally">
  ## 本地预览
</div>

请进入你的文档目录（`docs.json` 文件所在的位置），然后运行：

```bash theme={null}
mint dev
```

可以在 `http://localhost:3000` 本地预览文档。

或者，如果你不想全局安装命令行界面（CLI），可以运行一次性脚本：

```bash theme={null}
npx mint dev
```

<div id="custom-ports">
  ### 自定义端口
</div>

默认情况下，命令行界面（CLI）使用端口 3000。你可以使用 `--port` 选项来自定义端口。比如，要在 3333 端口上运行 CLI，请使用以下命令：

```bash theme={null}
mint dev --port 3333
```

如果你尝试在已被占用的端口上运行，命令行界面（CLI）会改用下一个可用端口：

```mdx theme={null}
端口 3000 已被占用。尝试使用 3001。
```

<div id="skip-openapi-processing">
  ## 跳过 OpenAPI 处理
</div>

如果你有大量 OpenAPI 文件，可以在本地开发时使用 `--disable-openapi` 参数跳过对 OpenAPI 文件的处理，从而提升性能：

```bash theme={null}
mint dev --disable-openapi
```

<div id="preview-as-a-specific-group">
  ### 以特定组预览
</div>

如果你使用部分认证来限制对文档的访问，可以通过 `--groups [groupname]` 标志，以特定认证组的身份进行预览。

例如，如果你有一个名为 `admin` 的组，可以使用以下命令以该组成员的身份进行预览：

```bash theme={null}
mint dev --groups admin
```

<div id="create-a-new-project">
  ## 创建新项目
</div>

要创建一个新的文档项目，请运行以下命令：

```bash theme={null}
mint new [directory]
```

此命令会将[入门套件](https://github.com/mintlify/starter)克隆到指定目录。若未指定目录，命令行界面（CLI）工具会提示你创建新的子目录或覆盖当前目录。

<Warning>
  如果你选择覆盖当前目录，其中的所有现有文件都会被删除。
</Warning>

CLI 工具会提示你输入项目名称和[主题](/zh/customize/themes)，以完成项目设置。

你可以使用以下参数运行 `mint new`：

* `--theme`：设置新项目的主题。
* `--name`：设置新项目的名称。
* `--force`：若当前目录已存在，则强制覆盖。

例如，要在 `docs` 目录中创建一个名为 `my-project`、主题为 `linden` 的新项目，请运行以下命令：

```bash theme={null}
mint new docs --name my-project --theme linden
```

<div id="update-the-cli">
  ## 更新命令行界面（CLI）
</div>

如果本地预览与线上生产环境中的内容不一致，请更新你的本地 CLI：

```bash theme={null}
mint update
```

如果本地版本中没有提供 `mint update` 命令，请使用最新版本重新安装命令行界面（CLI）：

<CodeGroup>
  ```bash npm theme={null}
  npm i -g mint@latest
  ```

  ```bash pnpm theme={null}
  pnpm add -g mint@latest
  ```
</CodeGroup>

<div id="additional-commands">
  ## 附加命令
</div>

<div id="find-broken-links">
  ### 查找损坏链接
</div>

使用以下命令检查并识别所有损坏的内部链接：

```bash theme={null}
mint broken-links
```

该命令会忽略与 [.mintignore](/zh/organize/mintignore) 模式相匹配的文件。指向这些被忽略文件的链接会被标记为损坏链接。

<div id="find-accessibility-issues">
  ### 查找无障碍问题
</div>

使用以下命令测试颜色对比度比例，并在文档中查找图像和视频缺失的 alt 文本：

```bash theme={null}
mint a11y
```

使用标志检查特定的无障碍问题。

```bash theme={null}
# Check only for missing alt text
mint a11y --skip-contrast

# 仅检查颜色对比度问题
mint a11y --skip-alt-text
```

<div id="check-openapi-spec">
  ### 检查 OpenAPI 规范
</div>

使用以下命令检查你的 OpenAPI 文件是否存在错误：

```bash theme={null}
mint openapi-check <OpenAPI 文件名或 URL>
```

传入文件名（例如 `./openapi.yaml`）或 URL（例如 `https://petstore3.swagger.io/api/v3/openapi.json`）。

<div id="rename-files">
  ### 重命名文件
</div>

使用以下命令重命名文件并更新所有对它们的引用：

```bash theme={null}
mint rename <旧文件名路径> <新文件名路径>
```

<div id="migrate-mdx-endpoint-pages">
  ### 迁移 MDX 端点页面
</div>

使用以下命令，将 MDX 端点页面迁移为基于你的 OpenAPI 规范自动生成的页面：

```bash theme={null}
mint migrate-mdx
```

此命令会将单个 MDX 端点页面转换为在你的 `docs.json` 中定义的自动生成页面，将 MDX 内容移至 OpenAPI 规范中的 `x-mint` 扩展，并更新你的导航。详见 [从 MDX 迁移](/zh/guides/migrating-from-mdx) 获取详细信息。

<div id="formatting">
  ## 格式化
</div>

在本地开发时，我们建议在你的 IDE 中安装相关扩展/插件，以便识别并格式化 MDX 文件。

如果你使用 Cursor、Windsurf 或 VS Code，我们推荐使用 [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) 进行语法高亮显示，并使用 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) 进行代码格式化。

如果你使用 JetBrains，我们推荐安装 [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) 以实现语法高亮显示，并配置 [Prettier](https://prettier.io/docs/webstorm) 进行代码格式化。

<div id="troubleshooting">
  ## 疑难解答
</div>

<AccordionGroup>
  <Accordion title="错误：无法在 darwin-arm64 运行时加载 'sharp' 模块">
    这可能是由于 Node 版本过旧。请尝试以下步骤：

    1. 卸载当前安装的 mint 命令行界面（CLI）：`npm uninstall -g mint`
    2. 升级到最新的 Node.js。
    3. 重新安装 mint 命令行界面（CLI）：`npm install -g mint`
  </Accordion>

  <Accordion title="问题：遇到未知错误">
    **解决方案**：进入用户主目录，删除 `~/.mintlify` 文件夹。然后再次运行 `mint dev`。
  </Accordion>

  <Accordion title="错误：permission denied">
    这是因为没有全局安装 Node 包所需的权限。

    **解决方案**：尝试运行 `sudo npm i -g mint`。系统会提示你输入密码，即用于解锁电脑的密码。
  </Accordion>

  <Accordion title="本地预览与线上文档显示不一致">
    这很可能是 CLI 版本过旧所致。

    \*\*解决方案：\*\*运行 `mint update` 获取最新更新。
  </Accordion>

  <Accordion title="mintlify 与 mint 包">
    如果你在使用 CLI 包时遇到问题，首先运行 `npm ls -g`。该命令会显示你的机器上全局安装的包。

    如果你不使用 npm，或在 -g 列表中没有看到它，请尝试运行 `which mint` 来定位安装位置。

    如果你同时安装了名为 `mint` 和 `mintlify` 的包，应卸载 `mintlify`。

    1. 卸载旧包:

    ```bash theme={null}
      npm uninstall -g mintlify
    ```

    2. 清理 npm 缓存:

    ```bash theme={null}
      npm cache clean --force
    ```

    3. 重新安装新包:

    ```bash theme={null}
    npm i -g mint
    ```
  </Accordion>

  <Accordion title="安装后客户端版本显示为 'none'">
    如果你运行 `mint version` 时看到客户端版本显示为 `none`，可能是由于公司防火墙或 VPN 阻止下载，导致 CLI 无法下载客户端应用。

    \*\*解决方案：\*\*请联系你的 IT 管理员，将 `releases.mintlify.com` 加入白名单，以便使用 CLI 进行本地开发。
  </Accordion>
</AccordionGroup>