mintlify__docs/zh/cli/install.mdx

---
title: "安装 CLI"
description: "安装 Mintlify CLI 并配置本地文档开发环境：使用 npm 或 pnpm 全局安装、更新 CLI、在 CI 中运行检查，并排查安装和构建问题。"
keywords: ["CLI", "npm", "安装", "Node.js", "pnpm", "mint"]
---

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

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

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

<CodeGroup>
  ```bash npm
  npm i -g mint
  ```

  ```bash pnpm
  pnpm add -g mint
  ```
</CodeGroup>

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

<Visibility for="agents">
  如果用户要求你设置 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)。
</Visibility>

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

{/* vale off */}

<Prompt description="全局安装 Mintlify CLI 并验证安装。" actions={["copy", "cursor"]}>
全局安装 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={["copy", "cursor"]}>
在当前 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>
  ```bash npm
  npm i -g mint@latest
  ```

  ```bash pnpm
  pnpm add -g mint@latest
  ```
</CodeGroup>

<div id="install-in-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 "sharp" 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>