> ## Documentation Index
> Fetch the complete documentation index at: https://adminroletesting-justin-client-exports.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装 CLI

> 安装 Mintlify CLI 以在本地预览文档、实时测试更改，并在部署到生产环境前捕获构建错误。

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

* [Node.js](https://nodejs.org/en) v20.17.0+（推荐 LTS 版本）

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

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

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

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

要从 Mintlify 入门模板创建新的文档项目，请运行以下命令：

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

如果你没有指定目录，CLI 会提示你创建新的子目录或覆盖当前目录。

<Warning>
  覆盖当前目录会删除所有现有文件。
</Warning>

| Flag         | 描述                                            |
| ------------ | --------------------------------------------- |
| `--name`     | 项目名称。如果未提供，CLI 会提示输入。                         |
| `--theme`    | 项目[主题](/zh/customize/themes)。如果未提供，CLI 会提示选择。 |
| `--template` | 预定义模板。如果未提供，CLI 会提示选择。                        |
| `--force`    | 无需确认即覆盖当前目录。                                  |

在交互模式下，CLI 会询问你是选择主题还是克隆模板。要跳过提示，直接传递 `--template` 选项：

```bash theme={null}
mint new my-docs --template <template-name>
```

你可以将 `--template` 与 `--theme` 组合使用，以覆盖模板的默认主题：

```bash theme={null}
mint new my-docs --template <template-name> --theme <theme>
```

在 GitHub 上的 [mintlify/templates](https://github.com/mintlify/templates) 仓库中查看可用模板。在交互模式下，CLI 会自动获取并显示可用模板。

在非交互式环境（如 CI/CD 流水线或 AI 编码代理）中，你必须提供 `--name` 和 `--theme` 选项，或者提供 `--template` 选项。

<div id="update">
  ## 更新
</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="formatting">
  ## 格式化
</div>

对于 MDX 文件中的语法高亮和代码格式化，我们推荐使用以下扩展：

* **Cursor、Devin Desktop、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="Error: Could not load the &#x22;sharp&#x22; module using the darwin-arm64 runtime">
    这可能是由于 Node.js 版本过旧导致的。请尝试以下步骤：

    1. 卸载当前版本的 mint CLI：`npm uninstall -g mint`
    2. 升级到 Node.js v20.17.0+。
    3. 重新安装 mint CLI：`npm install -g mint`
  </Accordion>

  <Accordion title="问题：遇到未知错误">
    **解决方案**：前往设备根目录，删除 `~/.mintlify` 文件夹。然后重新运行 `mint dev`。
  </Accordion>

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

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

  <Accordion title="本地预览与在线文档不一致">
    这可能是由于 CLI 版本过旧导致的。

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

  <Accordion title="mintlify 与 mint 包">
    如果你遇到 CLI 包的问题，首先运行 `npm ls -g` 查看全局安装了哪些包。如果你不使用 npm，请尝试 `which mint` 来定位安装位置。

    如果你同时安装了 `mint` 和 `mintlify` 包，请卸载 `mintlify`：

    ```bash theme={null}
    npm uninstall -g mintlify
    npm cache clean --force
    npm i -g mint
    ```
  </Accordion>

  <Accordion title="安装后客户端版本显示 'none'">
    如果运行 `mint version` 后客户端版本显示为 `none`，可能是 CLI 因企业防火墙或 VPN 而无法下载客户端应用程序。

    **解决方案**：请你的 IT 管理员将 `releases.mintlify.com` 添加到网络允许列表中。
  </Accordion>

  <Accordion title="使用 npx 时 CLI 连接到 localhost 而不是生产环境">
    在 `4.0.1125` 之前的版本中，从文档仓库运行 `npx mint dev` 或其他命令时，CLI 可能会
    将自身错误地识别为本地开发构建。这会导致 CLI 指向 `localhost` URL 而不是 Mintlify
    生产 API，从而引发连接错误或意外行为。

    **解决方案**：更新到最新的 CLI 版本：

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