> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/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/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/installation/local-development-light.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=6525a601adf38652082acfa170797829" 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/omer-914cc1c6/1pfjDJXEL6HIHDKE/images/installation/local-development-dark.png?fit=max&auto=format&n=1pfjDJXEL6HIHDKE&q=85&s=c3239d807129b6f835400e3d926d964c" width="1184" height="320" data-path="images/installation/local-development-dark.png" />

<div id="installing-the-cli">
  ## 安装命令行界面（CLI）
</div>

<Info>
  **先决条件**：继续之前，请先安装 [Node.js](https://nodejs.org/en)。
</Info>

<Steps>
  <Step title="安装 CLI。">
    运行以下命令安装 [CLI](https://www.npmjs.com/package/mint)：

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

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

  <Step title="本地预览。">
    进入你的文档目录（`docs.json` 所在位置），并执行以下命令：

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

    你的文档将可在 `http://localhost:3000` 进行本地预览。
  </Step>
</Steps>

或者，如果你不想全局安装 CLI，可以运行一次性脚本：

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

<div id="updates">
  ## 更新
</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="custom-ports">
  ## 自定义端口
</div>

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

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

如果你尝试使用已被占用的端口运行，它会切换到下一个可用端口：

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

<div id="previewing-as-a-specific-group">
  ## 以特定分组身份预览
</div>

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

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

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

<div id="additional-commands">
  ## 其他命令
</div>

虽然 `mint dev` 是最常用的命令，但你也可以使用其他命令来管理文档。

<div id="finding-broken-links">
  ### 查找断链
</div>

命令行界面（CLI）可以帮助你验证文档中的引用链接。要检测是否存在断链，请使用以下命令：

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

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

您可以使用命令行界面（CLI）运行以下命令来检查 OpenAPI 文件是否存在错误：

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

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

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

你可以使用以下命令重命名文件并更新对这些文件的所有引用：

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

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

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

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

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

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

在本地开发时，建议在你的 IDE 中使用扩展来识别并格式化 `MDX` 文件。

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

如果你使用 JetBrains，我们推荐用于语法高亮的 [MDX IntelliJ IDEA 插件](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>
</AccordionGroup>