mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
f2a988ab82
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
345 lines
11 KiB
Plaintext
345 lines
11 KiB
Plaintext
---
|
||
title: "安装 CLI"
|
||
description: "使用命令行界面（CLI）在本地预览文档、实时测试更改，并在部署文档站点之前发现问题。"
|
||
keywords: ["CLI", "npm", "本地开发", "Node.js", "pnpm", "mint dev", "断链", "无障碍"]
|
||
---
|
||
|
||
<img className="block dark:hidden my-0 pointer-events-none" src="/images/installation/local-development-light.png" alt="用于表示 CLI 的装饰性图形。" />
|
||
|
||
<img className="hidden dark:block my-0 pointer-events-none" src="/images/installation/local-development-dark.png" alt="用于表示 CLI 的装饰性图形。" />
|
||
|
||
使用 [CLI](https://www.npmjs.com/package/mint) 在撰写和编辑时本地预览文档。上线前即可实时查看更改、测试文档站点的外观与功能，并及时发现断链或无障碍问题等故障。
|
||
|
||
CLI 还提供维护文档的实用工具，包括用于重命名文件、验证 OpenAPI 规范以及在不同格式之间迁移 content 的命令。
|
||
|
||
<div id="prerequisites">
|
||
## 前提条件
|
||
</div>
|
||
|
||
* 已安装 [Node.js](https://nodejs.org/en) v20.17.0 及以上版本（推荐使用 LTS 版本）
|
||
* 已安装 [Git](https://git-scm.com/downloads)
|
||
* 已将你的文档存储库克隆到本地
|
||
|
||
<div id="clone-your-repository">
|
||
### 克隆你的存储库
|
||
</div>
|
||
|
||
<Steps>
|
||
<Step title="定位你的存储库">
|
||
1. 前往控制台中的 [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 页面。
|
||
2. 记下你的存储库位置。它会是以下格式之一：
|
||
|
||
* `mintlify-community/docs-{org-name}-{id}`（Mintlify 托管的存储库）
|
||
* `your-org/your-repo`（你自己的 GitHub 存储库）
|
||
</Step>
|
||
|
||
<Step title="克隆你的存储库">
|
||
<Tabs>
|
||
<Tab title="你自己的存储库">
|
||
将 `your-org/your-repo` 替换为你在 [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 中看到的实际存储库信息。
|
||
|
||
```bash
|
||
git clone https://github.com/your-org/your-repo
|
||
cd your-repo
|
||
```
|
||
|
||
<Tip>
|
||
**需要 GitHub App。** 若要在你推送更改时启用自动部署，必须安装 GitHub 应用。更多信息请参见 [GitHub](/zh/deploy/github)。
|
||
</Tip>
|
||
</Tab>
|
||
|
||
<Tab title="Mintlify 托管的存储库">
|
||
你可以将存储库克隆为私有或公开存储库。公开存储库对所有访问该存储库 URL 的人可见，私有存储库仅对你所在组织中的成员可见。
|
||
|
||
在控制台的 [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) 页面，选择 **Clone as private** 或 **Clone as public**。
|
||
</Tab>
|
||
</Tabs>
|
||
</Step>
|
||
</Steps>
|
||
|
||
<div id="install-the-cli">
|
||
## 安装 CLI
|
||
</div>
|
||
|
||
运行以下命令来安装 CLI：
|
||
|
||
<CodeGroup>
|
||
```bash npm
|
||
npm i -g mint
|
||
```
|
||
|
||
```bash pnpm
|
||
pnpm add -g mint
|
||
```
|
||
</CodeGroup>
|
||
|
||
<div id="preview-locally">
|
||
## 本地预览
|
||
</div>
|
||
|
||
请进入你的文档目录（`docs.json` 文件所在的位置），然后运行：
|
||
|
||
```bash
|
||
mint dev
|
||
```
|
||
|
||
可以在 `http://localhost:3000` 本地预览文档。
|
||
|
||
或者，如果你不想全局安装命令行界面（CLI），可以运行一次性脚本：
|
||
|
||
```bash
|
||
npx mint dev
|
||
```
|
||
|
||
<div id="custom-ports">
|
||
### 自定义端口
|
||
</div>
|
||
|
||
默认情况下，命令行界面（CLI）使用端口 3000。你可以使用 `--port` 选项来自定义端口。比如，要在 3333 端口上运行 CLI，请使用以下命令：
|
||
|
||
```bash
|
||
mint dev --port 3333
|
||
```
|
||
|
||
如果你尝试在已被占用的端口上运行，命令行界面（CLI）会改用下一个可用端口：
|
||
|
||
```mdx
|
||
端口 3000 已被占用。尝试使用 3001。
|
||
```
|
||
|
||
<div id="skip-openapi-processing">
|
||
## 跳过 OpenAPI 处理
|
||
</div>
|
||
|
||
如果你有大量 OpenAPI 文件，可以在本地开发时使用 `--disable-openapi` 参数跳过对 OpenAPI 文件的处理，从而提升性能：
|
||
|
||
```bash
|
||
mint dev --disable-openapi
|
||
```
|
||
|
||
<div id="preview-as-a-specific-group">
|
||
### 以特定组预览
|
||
</div>
|
||
|
||
如果你使用基于分组的访问控制来限制对文档的访问，可以通过 `--groups [groupname]` 标志，以特定认证组的身份进行预览。
|
||
|
||
例如，如果你有一个名为 `admin` 的组，可以使用以下命令以该组成员的身份进行预览：
|
||
|
||
```bash
|
||
mint dev --groups admin
|
||
```
|
||
|
||
|
||
<div id="create-a-new-project">
|
||
## 创建新项目
|
||
</div>
|
||
|
||
要创建一个新的文档项目，请运行以下命令：
|
||
|
||
```bash
|
||
mint new [directory]
|
||
```
|
||
|
||
此命令会将[入门套件](https://github.com/mintlify/starter)克隆到指定目录。若未指定目录，命令行界面（CLI）工具会提示你创建新的子目录或覆盖当前目录。
|
||
|
||
<Warning>
|
||
如果你选择覆盖当前目录，其中的所有现有文件都会被删除。
|
||
</Warning>
|
||
|
||
CLI 工具会提示你输入项目名称和[主题](/zh/customize/themes)，以完成项目设置。
|
||
|
||
<div id="flags">
|
||
### 标志
|
||
</div>
|
||
|
||
| 标志 | 说明 | 是否必填 |
|
||
| --- | --- | --- |
|
||
| `--name` | 设置新项目的名称。 | 是 |
|
||
| `--theme` | 设置新项目的[主题](/zh/customize/themes)。 | 是 |
|
||
| `--force` | 在不提示的情况下覆盖当前目录，即使其中包含现有文件。 | 否 |
|
||
|
||
在非交互式环境（例如 CI/CD 流水线或使用 AI 编码代理工具）中运行 `mint new` 时，必须提供所有必填标志（`--name` 和 `--theme`）。
|
||
|
||
<Tip>
|
||
命令行界面（CLI）会自动检测非交互式环境。如果缺少必填标志，它会输出使用说明，而不会在等待输入时卡住。
|
||
</Tip>
|
||
|
||
<div id="update-the-cli">
|
||
## 更新命令行界面（CLI）
|
||
</div>
|
||
|
||
如果本地预览与线上生产环境中的内容不一致，请更新你的本地 CLI：
|
||
|
||
```bash
|
||
mint update
|
||
```
|
||
|
||
如果本地版本中没有提供 `mint update` 命令，请使用最新版本重新安装命令行界面（CLI）：
|
||
|
||
<CodeGroup>
|
||
```bash npm
|
||
npm i -g mint@latest
|
||
```
|
||
|
||
```bash pnpm
|
||
pnpm add -g mint@latest
|
||
```
|
||
</CodeGroup>
|
||
|
||
<div id="additional-commands">
|
||
## 附加命令
|
||
</div>
|
||
|
||
<div id="find-broken-links">
|
||
### 查找损坏链接
|
||
</div>
|
||
|
||
使用以下命令检查并识别所有损坏的内部链接：
|
||
|
||
```bash
|
||
mint broken-links
|
||
```
|
||
|
||
该命令会忽略与 [.mintignore](/zh/organize/mintignore) 模式相匹配的文件。指向这些被忽略文件的链接会被标记为损坏链接。
|
||
|
||
<div id="find-accessibility-issues">
|
||
### 查找无障碍问题
|
||
</div>
|
||
|
||
使用以下命令测试颜色对比度比例，并在文档中查找图像和视频缺失的 alt 文本：
|
||
|
||
```bash
|
||
mint a11y
|
||
```
|
||
|
||
使用标志检查特定的无障碍问题。
|
||
|
||
```bash
|
||
# Check only for missing alt text
|
||
mint a11y --skip-contrast
|
||
|
||
# 仅检查颜色对比度问题
|
||
mint a11y --skip-alt-text
|
||
```
|
||
|
||
<div id="validate-documentation-build">
|
||
### 验证文档构建
|
||
</div>
|
||
|
||
在严格模式下验证你的文档构建；如果存在任何警告或错误，则会以错误状态退出。在 CI/CD 流水线中使用此命令，以防止有问题的文档被部署。
|
||
|
||
```bash
|
||
mint validate
|
||
```
|
||
|
||
使用标志配置验证命令。
|
||
|
||
* `--groups [groupname]`：为验证模拟用户组（在测试基于用户组的访问控制时很有用）
|
||
* `--disable-openapi`：在验证过程中禁用 OpenAPI 文件生成
|
||
|
||
|
||
<div id="check-openapi-spec">
|
||
### 检查 OpenAPI 规范
|
||
</div>
|
||
|
||
使用以下命令检查你的 OpenAPI 文件是否存在错误：
|
||
|
||
```bash
|
||
mint openapi-check <OpenAPI 文件名或 URL>
|
||
```
|
||
|
||
传入文件名（例如 `./openapi.yaml`）或 URL（例如 `https://petstore3.swagger.io/api/v3/openapi.json`）。
|
||
|
||
<div id="rename-files">
|
||
### 重命名文件
|
||
</div>
|
||
|
||
使用以下命令重命名文件并更新所有对它们的引用：
|
||
|
||
```bash
|
||
mint rename <旧文件名路径> <新文件名路径>
|
||
```
|
||
|
||
<div id="migrate-mdx-endpoint-pages">
|
||
### 迁移 MDX 端点页面
|
||
</div>
|
||
|
||
使用以下命令，将 MDX 端点页面迁移为基于你的 OpenAPI 规范自动生成的页面：
|
||
|
||
```bash
|
||
mint migrate-mdx
|
||
```
|
||
|
||
此命令会将单个 MDX 端点页面转换为在你的 `docs.json` 中定义的自动生成页面，将 MDX 内容移至 OpenAPI 规范中的 `x-mint` 扩展，并更新你的导航。详见 [从 MDX 迁移](/zh/guides/migrating-from-mdx) 获取详细信息。
|
||
|
||
<div id="formatting">
|
||
## 格式化
|
||
</div>
|
||
|
||
在本地开发时，我们建议在你的 IDE 中安装相关扩展/插件，以便识别并格式化 MDX 文件。
|
||
|
||
如果你使用 Cursor、Windsurf 或 VS Code，我们推荐使用 [MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) 进行语法高亮显示，并使用 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) 进行代码格式化。
|
||
|
||
如果你使用 JetBrains，我们推荐安装 [MDX IntelliJ IDEA plugin](https://plugins.jetbrains.com/plugin/14944-mdx) 以实现语法高亮显示，并配置 [Prettier](https://prettier.io/docs/webstorm) 进行代码格式化。
|
||
|
||
<div id="troubleshooting">
|
||
## 疑难解答
|
||
</div>
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="错误：无法在 darwin-arm64 运行时加载 'sharp' 模块">
|
||
这可能是由于 Node 版本过旧。请尝试以下步骤：
|
||
|
||
1. 卸载当前安装的 mint 命令行界面（CLI）：`npm uninstall -g mint`
|
||
2. 升级到 Node.js v20.17.0 或更高版本。
|
||
3. 重新安装 mint 命令行界面（CLI）：`npm install -g mint`
|
||
</Accordion>
|
||
|
||
<Accordion title="问题：遇到未知错误">
|
||
**解决方案**：进入用户主目录，删除 `~/.mintlify` 文件夹。然后再次运行 `mint dev`。
|
||
</Accordion>
|
||
|
||
<Accordion title="错误：permission denied">
|
||
这是因为没有全局安装 Node 包所需的权限。
|
||
|
||
**解决方案**：尝试运行 `sudo npm i -g mint`。系统会提示你输入密码，即用于解锁电脑的密码。
|
||
</Accordion>
|
||
|
||
<Accordion title="本地预览与线上文档显示不一致">
|
||
这很可能是 CLI 版本过旧所致。
|
||
|
||
**解决方案：**运行 `mint update` 获取最新更新。
|
||
</Accordion>
|
||
|
||
<Accordion title="mintlify 与 mint 包">
|
||
如果你在使用 CLI 包时遇到问题，首先运行 `npm ls -g`。该命令会显示你的机器上全局安装的包。
|
||
|
||
如果你不使用 npm，或在 -g 列表中没有看到它，请尝试运行 `which mint` 来定位安装位置。
|
||
|
||
如果你同时安装了名为 `mint` 和 `mintlify` 的包，应卸载 `mintlify`。
|
||
|
||
1. 卸载旧包:
|
||
|
||
```bash
|
||
npm uninstall -g mintlify
|
||
```
|
||
|
||
2. 清理 npm 缓存:
|
||
|
||
```bash
|
||
npm cache clean --force
|
||
```
|
||
|
||
3. 重新安装新包:
|
||
|
||
```bash
|
||
npm i -g mint
|
||
```
|
||
</Accordion>
|
||
|
||
<Accordion title="安装后客户端版本显示为 'none'">
|
||
如果你运行 `mint version` 时看到客户端版本显示为 `none`，可能是由于公司防火墙或 VPN 阻止下载，导致 CLI 无法下载客户端应用。
|
||
|
||
**解决方案：**请联系你的 IT 管理员，将 `releases.mintlify.com` 加入白名单，以便使用 CLI 进行本地开发。
|
||
</Accordion>
|
||
</AccordionGroup> |