跳转到主要内容
用于表示 CLI 的装饰性图形。 使用命令行界面（CLI）在编写和编辑时本地预览文档。在部署前实时查看更改，测试文档站点的外观与功能，并及时发现断链或无障碍等问题。 CLI 还提供维护文档的实用工具，包括用于重命名文件、验证 OpenAPI 规范，以及在不同格式之间迁移内容的命令。

​
安装命令行界面（CLI）

前提条件：CLI 需要 Node.js v19 或更高版本。
运行以下命令安装 CLI： 
npm i -g mint

​
本地预览

要在本地生成预览，请进入你的文档目录（docs.json 文件所在的位置），然后运行以下命令： 
mint dev
可以在 http://localhost:3000 本地预览文档。 或者，如果你不想全局安装命令行界面（CLI），可以运行一次性脚本： 
npx mint dev

​
自定义端口

默认情况下，命令行界面（CLI）使用端口 3000。你可以使用 --port 选项来自定义端口。比如，要在 3333 端口上运行 CLI，请使用以下命令： 
mint dev --port 3333
如果你尝试使用已占用的端口运行，它会改用下一个可用端口： 
端口 3000 已被占用。尝试使用 3001。

​
以特定组预览

如果你使用部分认证来限制对文档的访问，可以通过 --groups [groupname] 标志，以特定认证组的身份进行预览。 例如，如果你有一个名为 admin 的组，可以使用以下命令以该组成员的身份进行预览： 
mint dev --groups admin

​
创建新项目

要创建一个新的文档项目，请运行以下命令： 
mint new [目录]
此命令会将入门套件克隆到指定目录。若未指定目录，命令行界面（CLI）工具会提示你创建新的子目录或覆盖当前目录。
如果你选择覆盖当前目录，其中的所有现有文件都会被删除。
CLI 工具会提示你输入项目名称和主题，以完成项目设置。 你可以使用以下参数运行 mint new：
  • --theme：设置新项目的主题。
  • --name：设置新项目的名称。
  • --force：若当前目录已存在，则强制覆盖。
例如，要在 docs 目录中创建一个名为 my-project、主题为 linden 的新项目，请运行以下命令： 
mint new docs --name my-project --theme linden

​
更新命令行界面（CLI）

如果本地预览与线上生产环境中的内容不一致，请更新你的本地 CLI： 
mint update
如果本地版本中没有提供 mint update 命令，请使用最新版本重新安装命令行界面（CLI）： 
npm i -g mint@latest

​
附加命令

使用以下命令检查并识别所有损坏的内部链接： 
mint broken-links

​
查找无障碍问题

使用以下命令测试颜色对比度，并在文档中查找图像和视频缺失的 alt 文本： 
mint a11y

​
检查 OpenAPI 规范

使用以下命令检查你的 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