跳转到主要内容

​
安装命令行界面（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 content 移至 OpenAPI 规范中的 x-mint 扩展，并更新你的 navigation。详见从 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
⌘I