mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
97c7639c35
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
186 lines
7.3 KiB
Plaintext
186 lines
7.3 KiB
Plaintext
---
|
||
title: "安装 CLI"
|
||
description: "安装 Mintlify CLI 并配置本地文档开发环境，使用 npm 或 pnpm 管理全局安装，创建新项目、更新 CLI、格式化 MDX 文件，以及在发布前排查权限和构建问题。本文还说明 Node.js 版本要求、主题与模板选项、常用命令、交互式设置方式，以及本地预览异常和客户端下载失败时的处理方法。"
|
||
keywords: ["CLI", "npm", "安装", "Node.js", "pnpm", "mint"]
|
||
---
|
||
|
||
<div id="prerequisites">
|
||
## 前提条件
|
||
</div>
|
||
|
||
- [Node.js](https://nodejs.org/en) v20.17.0+（推荐 LTS 版本）
|
||
|
||
<div id="install-the-cli">
|
||
## 安装 CLI
|
||
</div>
|
||
|
||
<CodeGroup>
|
||
```bash npm
|
||
npm i -g mint
|
||
```
|
||
|
||
```bash pnpm
|
||
pnpm add -g mint
|
||
```
|
||
</CodeGroup>
|
||
|
||
<Visibility for="agents">
|
||
如果用户要求你设置 Mintlify，而不仅仅是安装 CLI，请继续完成身份验证、项目创建、预览、验证和部署。请遵循[快速入门中的 agent 设置工作流](/zh/quickstart#set-up-mintlify-for-the-user)。`mint --version` 成功后不要停止。
|
||
|
||
首先运行 `mint status`，并保留现有的已认证会话。否则，对于现有账户，运行 `mint login`。对于新账户，收集用户的真实姓名、公司和电子邮箱，并运行 `mint signup`。用户必须点击通过电子邮件发送的验证链接，并批准基于浏览器的身份验证。其余 CLI 步骤应由你执行。有关选项和后台进程指导，请参阅 [`mint signup`](/zh/cli/commands#mint-signup)。
|
||
</Visibility>
|
||
|
||
<Tip>
|
||
正在使用 AI 编码工具？复制下面的 prompt，让你的代理安装 CLI 并验证其是否正常工作。
|
||
</Tip>
|
||
|
||
{/* vale off */}
|
||
|
||
<Prompt description="全局安装 Mintlify CLI 并验证安装。" actions={["copy", "cursor"]}>
|
||
全局安装 Mintlify CLI，以便我可以在本地预览我的文档。
|
||
|
||
1. 通过运行 `node --version` 确认已安装 Node.js v20.17.0 或更新版本。如果缺失或版本过旧，请先告知我，再继续。
|
||
2. 使用 `npm i -g mint` 安装 CLI（如果我使用 pnpm，则使用 `pnpm add -g mint`）。
|
||
3. 通过运行 `mint --version` 验证安装，并分享输出。
|
||
4. 如果安装因权限错误失败，建议改用 `sudo` 重新运行，并说明其中的取舍。
|
||
</Prompt>
|
||
|
||
{/* vale on */}
|
||
|
||
<div id="create-a-new-project">
|
||
## 创建新项目
|
||
</div>
|
||
|
||
要从 Mintlify 入门模板创建新的文档项目，请运行以下命令：
|
||
|
||
```bash
|
||
mint new [directory]
|
||
```
|
||
|
||
{/* vale off */}
|
||
|
||
<Prompt description="搭建一个新的 Mintlify 项目。" actions={["copy", "cursor"]}>
|
||
在当前 workspace 中创建一个新的 Mintlify 项目。
|
||
|
||
1. 如果我尚未告诉你项目名称和首选主题（或模板），请向我索取。
|
||
2. 以非交互方式运行 `mint new <directory> --name <name> --theme <theme>`，替换为我提供的值。如果我选择了模板，则改为运行 `mint new <directory> --template <template-name>`。
|
||
3. 命令完成后，列出生成的文件，并指出 `docs.json` 是主要的配置入口。
|
||
4. 在新目录中运行 `mint dev`，并分享本地预览的 URL。
|
||
</Prompt>
|
||
|
||
{/* vale on */}
|
||
|
||
如果你没有指定目录，CLI 会提示你创建新的子目录或覆盖当前目录。
|
||
|
||
<Warning>
|
||
覆盖当前目录会删除所有现有文件。
|
||
</Warning>
|
||
|
||
| Flag | 描述 |
|
||
| --- | --- |
|
||
| `--name` | 项目名称。如果未提供，CLI 会提示输入。 |
|
||
| `--theme` | 项目[主题](/zh/customize/themes)。如果未提供，CLI 会提示选择。 |
|
||
| `--template` | 预定义模板。如果未提供，CLI 会提示选择。 |
|
||
| `--force` | 无需确认即覆盖当前目录。 |
|
||
|
||
在交互模式下，CLI 会询问你是选择主题还是克隆模板。要跳过提示，直接传递 `--template` 选项：
|
||
|
||
```bash
|
||
mint new my-docs --template <template-name>
|
||
```
|
||
|
||
你可以将 `--template` 与 `--theme` 组合使用，以覆盖模板的默认主题：
|
||
|
||
```bash
|
||
mint new my-docs --template <template-name> --theme <theme>
|
||
```
|
||
|
||
在 GitHub 上的 [mintlify/templates](https://github.com/mintlify/templates) 仓库中查看可用模板。在交互模式下，CLI 会自动获取并显示可用模板。
|
||
|
||
在非交互式环境（如 CI/CD 流水线或 AI 编码代理）中，你必须提供 `--name` 和 `--theme` 选项，或者提供 `--template` 选项。
|
||
|
||
<div id="update">
|
||
## 更新
|
||
</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="editor-support">
|
||
## 编辑器支持
|
||
</div>
|
||
|
||
对于 MDX 文件中的语法高亮、自动补全和错误检查，请使用以下扩展：
|
||
|
||
- **Cursor、Devin Desktop、VS Code**：[Mintlify MDX 扩展](/zh/cli/mdx-extension) 和用于格式化的 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)。
|
||
- **JetBrains**：[MDX IntelliJ IDEA 插件](https://plugins.jetbrains.com/plugin/14944-mdx) 和 [Prettier](https://prettier.io/docs/webstorm)。
|
||
|
||
你也可以使用 [`mint format`](/zh/cli/commands#mint-format) 格式化 MDX 文件。
|
||
|
||
<div id="troubleshooting">
|
||
## 故障排除
|
||
</div>
|
||
|
||
<AccordionGroup>
|
||
<Accordion title='Error: Could not load the "sharp" module using the darwin-arm64 runtime'>
|
||
这可能是由于 Node.js 版本过旧导致的。请尝试以下步骤：
|
||
|
||
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="Error: permission denied">
|
||
这是因为你没有全局安装 Node.js 包所需的权限。
|
||
|
||
**解决方案**：尝试运行 `sudo npm i -g mint`。出现提示时，输入你用于解锁电脑的密码。
|
||
</Accordion>
|
||
<Accordion title="本地预览与在线文档不一致">
|
||
这可能是由于 CLI 版本过旧导致的。
|
||
|
||
**解决方案**：运行 `mint update` 获取最新更改。
|
||
</Accordion>
|
||
<Accordion title="mintlify 与 mint 包">
|
||
如果 CLI 包出现问题，首先运行 `npm ls -g` 查看全局安装了哪些包。如果你不使用 npm，请尝试 `which mint` 来定位安装位置。
|
||
|
||
如果你同时安装了 `mint` 和 `mintlify` 包，请卸载 `mintlify`：
|
||
|
||
```bash
|
||
npm uninstall -g mintlify
|
||
npm cache clean --force
|
||
npm i -g mint
|
||
```
|
||
</Accordion>
|
||
<Accordion title="安装后客户端版本显示“none”">
|
||
如果运行 `mint version` 后客户端版本显示为 `none`，可能是 CLI 因企业防火墙或 VPN 而无法下载客户端应用程序。
|
||
|
||
**解决方案**：请你的 IT 管理员将 `releases.mintlify.com` 添加到网络允许列表中。
|
||
</Accordion>
|
||
<Accordion title="使用 npx 时 CLI 连接到 localhost 而不是生产环境">
|
||
在 `4.0.1125` 之前的版本中，从文档仓库运行 `npx mint dev` 或其他命令时，CLI 可能会将自身错误地识别为本地开发构建。此时，CLI 会指向 `localhost` URL，而不是 Mintlify 生产 API，进而引发连接错误或意外行为。
|
||
|
||
**解决方案**：更新到最新的 CLI 版本：
|
||
|
||
```bash
|
||
npm i -g mint@latest
|
||
```
|
||
</Accordion>
|
||
</AccordionGroup>
|