安装 CLI

安装 Mintlify CLI 并配置本地文档开发环境：使用 npm 或 pnpm 全局安装、更新 CLI、在 CI 中运行检查，并排查安装和构建问题。

​

前提条件

• Node.js v20.17.0+（推荐 LTS 版本）

​

安装 CLI

npm

npm i -g mint

CLI 在 npm 上以 mint 包的形式发布。请勿在安装脚本或 CI 流水线中安装旧版 mintlify 包。如果你同时安装了这两个包，请参见 mintlify 与 mint 包。

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

全局安装 Mintlify CLI 并验证安装。

已复制复制提示词在 Cursor 中打开

​

创建新项目

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

mint new [directory]

搭建一个新的 Mintlify 项目。

已复制复制提示词在 Cursor 中打开

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

覆盖当前目录会删除所有现有文件。

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

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

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

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

mint new my-docs --template <template-name> --theme <theme>

在 GitHub 上的 mintlify/templates 仓库中查看可用模板。在交互模式下，CLI 会自动获取并显示可用模板。

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

​

更新

如果你的本地预览与已部署的文档不同步，请将 CLI 更新到最新版本：

mint update

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

npm

npm i -g mint@latest

​

在 CI 中安装

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

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 在出现任何警告或错误时都会以错误退出，无需额外检查。

​

编辑器支持

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

• Cursor、Devin Desktop、VS Code：Mintlify MDX 扩展 和用于格式化的 Prettier。
• JetBrains：MDX IntelliJ IDEA 插件 和 Prettier。

你也可以使用 mint format 格式化 MDX 文件。

​

故障排除

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

问题：遇到未知错误

解决方案：打开终端，删除 ~/.mintlify 文件夹，然后重新运行 mint dev。

Error: permission denied

这是因为你没有全局安装 Node.js 包所需的权限。

解决方案：尝试运行 sudo npm i -g mint。出现提示时，输入你用于解锁电脑的密码。

本地预览与在线文档不一致

这可能是由于 CLI 版本过旧导致的。

解决方案：运行 mint update 获取最新更改。

mintlify 与 mint 包

如果 CLI 包出现问题，首先运行 npm ls -g 查看全局安装了哪些包。如果你不使用 npm，请尝试 which mint 来定位安装位置。

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

npm uninstall -g mintlify
npm cache clean --force
npm i -g mint

安装后客户端版本显示“none”

如果运行 mint version 后客户端版本显示为 none，可能是 CLI 因企业防火墙或 VPN 而无法下载客户端应用程序。

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

使用 npx 时 CLI 连接到 localhost 而不是生产环境

在 4.0.1125 之前的版本中，从文档仓库运行 npx mint dev 或其他命令时，CLI 可能会将自身错误地识别为本地开发构建。此时，CLI 会指向 localhost URL，而不是 Mintlify 生产 API，进而引发连接错误或意外行为。

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

npm i -g mint@latest