跳转到主要内容

​
安装 CLI

前置条件：请先安装 Node.js。
1

安装 CLI

运行以下命令安装 CLI：
npm i -g mint
2

本地预览

进入文档目录（docs.json 文件所在位置），并运行以下命令：
mint dev
你的文档将可在本地通过 http://localhost:3000 访问。
或者，如果你不想全局安装 CLI，可以运行一次性脚本： 
npx mint dev

​
更新

如果本地预览与线上生产环境显示不一致，请更新本地 CLI： 
mint update
如果你的本地版本中没有 mint update 命令，请重新安装最新版本的 CLI： 
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 <openapi文件名或URL>
你可以传入文件名（例如 ./openapi.yaml）或 URL（例如 https://petstore3.swagger.io/api/v3/openapi.json）。

​
重命名文件

你可以使用以下命令重命名文件并更新所有引用： 
mint rename <旧文件名> <新文件名>

​
迁移 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。

​
疑难解答

这可能是由于 Node 版本过旧。请尝试以下操作：
  1. 卸载当前已安装的 mint CLI：npm uninstall -g mint
  2. 升级到最新的 Node.js。
  3. 重新安装 mint CLI：npm install -g mint
解决方案：前往用户根目录并删除 ~/.mintlify 文件夹。然后再次运行 mint dev。
原因是缺少全局安装 Node 包所需的权限。解决方案：尝试运行 sudo npm i -g mint。系统会提示你输入密码，即用于解锁电脑的密码。
这很可能是由于 CLI 版本过旧。解决方案： 运行 mint update 获取最新更新。
如果在使用 CLI 包时遇到问题，首先运行 npm ls -g。该命令会显示机器上全局安装的包。如果你不使用 npm 或在 -g 列表中未看到它，尝试运行 which mint 来定位安装路径。如果同时安装了名为 mint 和 mintlify 的包，应卸载 mintlify。
  1. 卸载旧包：
  npm uninstall -g mintlify
  1. 清理 npm 缓存：
  npm cache clean --force
  1. 重新安装新包：
npm i -g mint