CLI 安装

安装 CLI 以在本地预览和开发文档

安装 CLI

前提条件：在继续之前，请先安装 Node.js。

1. 安装 CLI

   运行以下命令来安装 CLI：

   npm

   npm i -g mint
   

2. 本地预览

   进入你的文档目录（docs.json 所在位置），并执行以下命令：

   mint dev
   

   文档的本地预览将可通过 http://localhost:3000 访问。

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

npx mint dev

更新

如果你的本地预览与线上生产环境的显示不同步，请更新本地 CLI：

mint update

如果本地版本不支持 mint update 命令，请使用最新版本重新安装 CLI：

npm

npm i -g mint@latest

自定义端口

默认情况下，CLI 使用 3000 端口。你可以使用 --port 标志自定义端口。比如，要在 3333 端口上运行 CLI，请使用以下命令：

mint dev --port 3333

如果你尝试使用已被占用的端口，将自动使用下一个可用端口：

3000 端口已被占用。改为尝试 3001。

以特定群组预览

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

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

mint dev --group admin

其他命令

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

查找断链

CLI 可以帮助你验证文档中的引用链接。要识别任何断链，请使用以下命令：

mint broken-links

检查 OpenAPI 规范

你可以使用 CLI 通过以下命令检查 OpenAPI 文件是否存在错误：

mint openapi-check <openapiFilenameOrUrl>

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

重命名文件

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

mint rename <oldFilename> <newFilename>

迁移 MDX 端点页面

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

mint migrate-mdx

该命令会将单个 MDX 端点页面转换为在 docs.json 中定义的自动生成页面，将 MDX 内容移至 OpenAPI 规范中的 x-mint 扩展，并更新导航。详见从 MDX 迁移获取详细信息。

格式化

在本地开发时，建议在你的 IDE 中安装相应扩展，以识别并格式化 MDX 文件。

如果你使用 Cursor、Windsurf 或 VS Code，建议安装用于语法高亮的 MDX VS Code 扩展，以及用于代码格式化的 Prettier。

如果你使用 JetBrains，建议安装用于语法高亮的 MDX IntelliJ IDEA 插件，并配置 Prettier 进行代码格式化。

疑难解答

错误：无法在 darwin-arm64 运行时加载“sharp”模块

这可能是由于 Node 版本过旧。请尝试以下操作：

1. 卸载当前安装的 mint CLI：npm uninstall -g mint
2. 升级到最新的 Node.js
3. 重新安装 mint CLI：npm install -g mint

问题：遇到未知错误

解决方案：进入你的用户根目录并删除 ~/.mintlify 文件夹。然后再次运行 mint dev。

错误：permission denied

这是由于没有全局安装 Node 包所需的权限。

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

本地预览与网页上的文档显示不一致

这很可能是由于 CLI 版本过旧。

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

mintlify 与 mint 包

如果你在使用 CLI 包时遇到问题，首先运行 npm ls -g。该命令会显示你机器上全局安装了哪些包。

如果你不使用 npm，或在 -g 列表中没有看到它，尝试运行 which mint 来定位安装位置。

如果你同时安装了名为 mint 和名为 mintlify 的包，应卸载 mintlify。

1. 卸载旧包：

  npm uninstall -g mintlify

2. 清理 npm 缓存：

  npm cache clean --force

3. 重新安装新包：

npm i -g mint