# 安装 CLI (/zh/cli/install)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1682 · updated: 2026-09-23 -->
Related: [Mintlify MDX 扩展](/zh/cli/mdx-extension.md), [本地预览](/zh/cli/preview.md), [Mintlify CLI 命令参考](/zh/cli/commands.md), [AI 原生文档](/zh/ai-native.md)

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

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

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

<CodeGroup>
  <CodeBlockTabs defaultValue="npm" groupId="npm+pnpm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash  
      npm i -g mint
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash  
      pnpm add -g mint
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Note>
  CLI 在 npm 上以 [`mint`](https://www.npmjs.com/package/mint) 包的形式发布。请勿在安装脚本或 CI 流水线中安装旧版 `mintlify` 包。如果你同时安装了这两个包，请参见 [mintlify 与 mint 包](#troubleshooting)。
</Note>

如果用户要求你设置 Mintlify，而不仅仅是安装 CLI，请继续完成身份验证、项目创建、预览、验证和部署。请遵循[快速入门中的 agent 设置工作流](/zh/quickstart#set-up-mintlify-for-the-user)。`mint --version` 成功后不要停止。

首先运行 `mint status`，并保留现有的已认证会话。否则，对于现有账户，运行 `mint login`。对于新账户，收集用户的真实姓名、公司和电子邮箱，并运行 `mint signup`。用户必须点击通过电子邮件发送的验证链接，并批准基于浏览器的身份验证。其余 CLI 步骤应由你执行。有关选项和后台进程指导，请参阅 [`mint signup`](/zh/cli/commands#mint-signup)。

<Tip>
  正在使用 AI 编码工具？复制下面的 prompt，让你的代理安装 CLI 并验证其是否正常工作。
</Tip>

{/* vale off */}

<Prompt description="全局安装 Mintlify CLI 并验证安装。" actions="[&#x22;copy&#x22;, &#x22;cursor&#x22;]">
  全局安装 Mintlify CLI，以便我可以在本地预览我的文档。

  1. 通过运行 `node --version` 确认已安装 Node.js v20.17.0 或更新版本。如果缺失或版本过旧，请先告知我，再继续。
  2. 使用 `npm i -g mint` 安装 CLI（如果我使用 pnpm，则使用 `pnpm add -g mint`）。
  3. 通过运行 `mint --version` 验证安装，并分享输出。
  4. 如果安装因权限错误失败，建议改用 `sudo` 重新运行，并说明其中的取舍。
</Prompt>

{/* vale on */}

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

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

```bash
mint new [directory]
```

{/* vale off */}

<Prompt description="搭建一个新的 Mintlify 项目。" actions="[&#x22;copy&#x22;, &#x22;cursor&#x22;]">
  在当前 workspace 中创建一个新的 Mintlify 项目。

  1. 如果我尚未告诉你项目名称和首选主题（或模板），请向我索取。
  2. 以非交互方式运行 `mint new <directory> --name <name> --theme <theme>`，替换为我提供的值。如果我选择了模板，则改为运行 `mint new <directory> --template <template-name>`。
  3. 命令完成后，列出生成的文件，并指出 `docs.json` 是主要的配置入口。
  4. 在新目录中运行 `mint dev`，并分享本地预览的 URL。
</Prompt>

{/* vale on */}

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

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

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

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

```bash
mint new my-docs --template <template-name>
```

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

```bash
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
mint update
```

如果你的版本中没有 `mint update`，请使用最新版本重新安装 CLI：

<CodeGroup>
  <CodeBlockTabs defaultValue="npm" groupId="npm+pnpm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash  
      npm i -g mint@latest
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash  
      pnpm add -g mint@latest
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<div id="install-in-ci">
  ## 在 CI 中安装 [#在-ci-中安装]
</div>

要在持续集成流水线中运行 CLI 检查，请全局安装 `mint` 包，然后运行你需要的命令。例如，下面这个 GitHub Actions 作业使用 [`mint format`](/zh/cli/commands#mint-format) 检查格式，并使用 [`mint validate`](/zh/cli/commands#mint-validate) 验证构建：

```yaml
name: Docs checks

on:
  pull_request:
    paths:
      - "**/*.mdx"
      - "docs.json"

jobs:
  docs-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install the Mintlify CLI
        run: npm i -g mint
      - name: Check formatting
        run: |
          mint format
          if [ -n "$(git status --porcelain)" ]; then
            echo "Files are not formatted. Run 'mint format' locally and commit the changes."
            exit 1
          fi
      - name: Validate the build
        run: mint validate
```

`mint format` 会就地重写文件，并在任何文件解析失败时以退出码 `1` 结束，因此该作业会在其运行后检查是否存在 diff。`mint validate` 在出现任何警告或错误时都会以错误退出，无需额外检查。

<div id="editor-support">
  ## 编辑器支持 [#编辑器支持]
</div>

对于 MDX 文件中的语法高亮、自动补全和错误检查，请使用以下扩展：

* **Cursor、Devin Desktop、VS Code**：[Mintlify MDX 扩展](/zh/cli/mdx-extension) 和用于格式化的 [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)。

你也可以使用 [`mint format`](/zh/cli/commands#mint-format) 格式化 MDX 文件。

<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.js 包所需的权限。

    **解决方案**：尝试运行 `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
    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
    npm i -g mint@latest
    ```
  </Accordion>
</AccordionGroup>