--- title: CLI 概览 description: >- 使用开源 Jamdesk CLI 在本地预览文档、验证配置、检查断链并迁移平台。 --- > **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version. Jamdesk CLI 可用于在本地预览文档、验证配置、检查断链，以及从其他平台迁移。它基于 [Apache License 2.0](https://github.com/jamdesk/jamdesk-cli) 开源。 ## 安装从 [npm](https://www.npmjs.com/package/jamdesk) 全局安装，即可在任意位置使用 `jamdesk`： ```bash npm install -g jamdesk ``` 在 macOS 或 Linux 上通过 Homebrew 安装： ```bash brew tap jamdesk/tap brew install jamdesk ``` 通过脚本安装： ```bash curl -fsSL https://get.jamdesk.com | bash ``` 升级或卸载： ```bash curl -fsSL https://get.jamdesk.com/upgrade | bash curl -fsSL https://get.jamdesk.com/uninstall | bash ``` 通过脚本安装： ```powershell iwr https://get.jamdesk.com/win | iex ``` 升级或卸载： ```powershell iwr https://get.jamdesk.com/upgrade | iex iwr https://get.jamdesk.com/uninstall | iex ``` 无需安装即可运行： ```bash npx jamdesk dev ``` 安装后，验证 CLI 是否正常运行： ```bash jamdesk --version ``` ### 要求 - **Node.js** v20.0.0 或更高版本 - **npm** v8 或更高版本（推荐） ## 快速开始创建新的文档项目： ```bash jamdesk init my-docs cd my-docs ``` 启动支持热重载的本地开发服务器： ```bash jamdesk dev ``` 文档将在 **http://localhost:3000/docs** 提供访问检查配置错误、断链和拼写错误： ```bash jamdesk validate jamdesk broken-links jamdesk fix --dry-run jamdesk fix jamdesk spellcheck ``` ## 命令运行 `jamdesk --help`，获取任意命令的详细信息。 ### 开发启动支持热重载的本地开发服务器。 ```bash jamdesk dev jamdesk dev --port 3001 ``` **功能：** - 启动时自动验证（docs.json 架构、MDX 语法和引用的 OpenAPI 规范；规范无效时服务器会停止，以便在部署前发现问题） - MDX 文件变更时热重载 - docs.json 变更时自动重建导航 - 自定义 CSS（`style.css`）在浏览器刷新时重新加载 - 完整的搜索功能 - 提供所有主题和组件 **选项：** | 标志 | 描述 | |------|-------------| | `-p, --port ` | 运行端口（默认为 3000） | | `-v, --verbose` | 启用详细输出 | 创建新的文档项目。 ```bash jamdesk init # Interactive mode jamdesk init my-docs # Create in new directory ``` 此命令会创建包含以下内容的新项目： - `docs.json` 配置文件 - 示例 MDX 页面 - 推荐的文件夹结构 ### 身份验证通过浏览器登录 Jamdesk。部署前必须完成登录。 ```bash jamdesk login ``` 在浏览器中打开 Jamdesk 仪表板进行身份验证。凭据会存储在本地 `~/.jamdeskrc` 中。基于浏览器的身份验证流程、会话管理和故障排除清除已存储的凭据。 ```bash jamdesk logout ``` 显示当前已验证的用户，并验证会话是否有效。 ```bash jamdesk whoami ``` ### 验证验证 `docs.json` 配置、MDX 语法和 OpenAPI 规范。 ```bash jamdesk validate jamdesk validate --skip-mdx ``` **检查内容：** - docs.json 中的有效 JSON 语法 - 必填字段（name、navigation） - 有效的主题值 - MDX 语法错误（例如未转义的 `<` 字符） - OpenAPI 规范验证（如果已配置） - 架构合规性 **选项：** | 标志 | 描述 | |------|-------------| | `--skip-mdx` | 跳过 MDX 语法验证 | | `-v, --verbose` | 显示详细的验证输出 | 在部署前运行此命令，以便尽早发现错误。扫描文档中的断链。 ```bash jamdesk broken-links ``` **示例输出：** ```text docs/getting-started.mdx:15 - /docs/quikstart Did you mean: /docs/quickstart Found 1 broken link in 45 files. ``` 此命令会检测指向缺失页面的链接和拼写错误。详情请参阅 [链接与导航](/cn/content/links#如何检测内部链接)。自动修复具有明确目标的断链警告。支持以下两类问题： - **拼写错误的锚点**：例如 `#instalation` 这类片段，明显应为 `#installation` - **跨语言锚点漂移**：翻译页面重命名了标题，但该语言中的链接仍指向旧的英文片段 ```bash # Preview what would change without touching any files jamdesk fix --dry-run # Apply fixes (prompts for confirmation) jamdesk fix ``` **试运行输出示例：** ```text Planned fixes: fr/ai/overview.mdx:9 /fr/ai/selectors#ai-strategies → /fr/ai/selectors#stratégies-ia (dry run — no files written) ``` 只有在修正后的锚点能够解析到目标页面中的真实标题时，才会写入修复结果。存在歧义的情况会留待手动检查。 **选项：** | 标志 | 描述 | |------|-------------| | `--dry-run` | 预览计划中的修复，不写入任何文件 | | `-y, --yes` | 无需确认提示即可应用修复 | | `--types ` | 要修复的警告类型，以逗号分隔（默认为所有受支持的类型） | 分步介绍预览、应用、检查和提交修复检查文档中的拼写错误。 ```bash jamdesk spellcheck ``` **示例输出：** ```text getting-started.mdx:14 - "recieve" └─ Did you mean: receive Found 3 misspellings across 24 pages. Tip: Run "jamdesk spellcheck --fix" to interactively fix or ignore words. ``` 此命令使用包含 150 多个内置技术术语（API、GraphQL、Kubernetes、React 等）的英语词典，因此常见术语不会被误报。它会跳过代码块、内联代码、frontmatter、JSX、URL 和文件路径。目前仅支持英语，计划提供多语言词典支持。 **选项：** | 标志 | 描述 | |------|-------------| | `--fix` | 交互式修复拼写错误，或将其添加到忽略列表 | | `--json` | 以 JSON 格式输出（用于 CI 流水线） | | `-v, --verbose` | 显示正在检查的每个文件 | **交互式修复模式（`--fix`）** 会逐一处理每个不重复的拼写错误： ```text 1/10 "recieve" — found in 3 files intro.mdx:14, setup.mdx:7, guide.mdx:22 ? What do you want to do? ❯ Fix → receive (recommended) Fix → relieve Ignore in the future (add to docs.json) Skip ``` - **Fix** 会在所有文件中使用建议词替换该单词（确保不会修改代码块或 JSX 属性，因此适用于普通文本）。最多显示 3 个建议，并将最佳匹配标记为推荐项。 - **Ignore** 会将该单词添加到 docs.json 的 `spellcheck.ignore` 中，使其不再被标记 - **Skip** 本次运行不执行任何操作应用更改前会预览并请求确认。 **自定义忽略列表：** 将项目专用术语添加到 docs.json： ```json docs.json { "spellcheck": { "ignore": ["YourProduct", "kubectl", "Terraform"] } } ``` docs.json 中的项目名称会自动被忽略。验证单个 OpenAPI 规范文件。 ```bash jamdesk openapi-check openapi.yaml jamdesk openapi-check api/spec.json ``` **验证内容：** - 有效的 YAML/JSON 语法 - OpenAPI 3.x 架构合规性 - 端点定义 - `$ref` 引用可正确解析 **OpenAPI 规范会在三个地方进行验证。** 如果引用的规范无效，`jamdesk dev` 会在启动时停止；`jamdesk validate` / `jamdesk openapi-check` 会按需检查规范。部署时，云端构建也会验证引用的规范，但这属于**非致命警告**：其余文档仍会发布，并通过电子邮件和仪表板的构建列表准确告知问题所在（包括带行号和列号的解析错误、无法解析的 `$ref` 或重复的 `operationId`）。修复规范后再次推送即可清除警告。 ### 文件管理重命名页面并自动更新所有引用。 ```bash jamdesk rename docs/old-name.mdx docs/new-name.mdx ``` **此命令会：** - 重命名文件 - 更新 docs.json 导航 - 更新其他所有 MDX 文件中的链接 - 更新片段引用请使用此命令代替手动重命名，以保持所有引用同步。 ### 迁移将文档从 Mintlify 迁移到 Jamdesk。 ```bash jamdesk migrate ``` 此命令会检测 Mintlify 配置并将其转换为 Jamdesk 格式。在同一过程中，它还会重命名已弃用的组件（例如 `CardGroup` → `Columns`）、将无父级的片段 MDX 文件移动到 `/snippets/` 并重写父级相对导入，将使用 React hooks 的内联组件提取到 `/snippets/.tsx` 并添加 `'use client'`，以及自动修复机械性的 MDX 语法问题。该命令具有幂等性，因此可以安全地重复运行。面向 Mintlify 和其他平台的完整分步迁移指南 ### 部署从终端上传文档并直接触发构建。 ```bash jamdesk deploy jamdesk deploy --detach jamdesk deploy --full-rebuild ``` 每个构建阶段完成时都会实时显示进度。也可以使用 `jamdesk push`。 | 标志 | 描述 | |------|-------------| | `--detach` | 将任务加入队列后立即退出 | | `--full-rebuild` | 强制完整重建（不使用缓存） | | `--project ` | 部署到指定项目 | | `--allow-empty` | 允许部署包含零个 `.mdx` 内容页面的项目（默认拒绝） | 完整部署流程、构建阶段、错误参考和故障排除构建并部署 Cloudflare Worker，将自有域名上的 `/docs` 代理到 Jamdesk 站点。 ```bash jamdesk deploy-proxy cloudflare jamdesk deploy-proxy cloudflare --slug myproject --domain example.com --yes ``` 默认采用交互式模式：检查 Wrangler、验证 Cloudflare 账户、从 docs.json 自动检测 slug、生成 Worker 文件，并可选择部署。使用 `--yes` 时，命令只生成文件后停止——请在输出目录中运行 `npx wrangler deploy` 进行部署。 | 标志 | 描述 | |------|-------------| | `--slug ` | Jamdesk 项目 slug | | `--domain ` | 目标域名（例如 `example.com`） | | `--path ` | 路径前缀（默认为 `/docs`） | | `--output-dir ` | 输出目录（默认为 `cloudflare-worker/`） | | `--skip-deploy` | 在交互式运行中跳过“立即部署？”提示 | | `--force` | 如果输出目录已存在则覆盖 | | `--yes` | 对所有提示使用默认答案（CI 模式）。不会部署，也不会覆盖现有目录 | Worker 设置、路由模式和缓存配置 ### 维护检查环境并诊断问题。 ```bash jamdesk doctor ``` **检查内容：** - Node.js 版本（要求 v20+） - npm 版本 - docs.json 是否存在且有效 - ~/.jamdesk 缓存状态 - 写入权限如果 CLI 遇到问题，请运行此命令。清除 ~/.jamdesk 缓存目录。 ```bash jamdesk clean ``` 此命令会移除缓存的依赖项和构建产物。可用于： - 释放磁盘空间 - 修复损坏的缓存问题 - 强制重新安装依赖项下次运行 `jamdesk dev` 时会重新安装依赖项。将 CLI 更新到最新版本。 ```bash jamdesk update ``` 也可以手动更新： ```bash npm update -g jamdesk ``` ## 配置创建 `~/.jamdeskrc` 以设置默认选项： ```json { "defaultPort": 3001, "verbose": false, "checkUpdates": true } ``` | 选项 | 类型 | 默认值 | 描述 | |--------|------|---------|-------------| | `defaultPort` | number | 3000 | 开发服务器的默认端口 | | `verbose` | boolean | false | 默认启用详细输出 | | `checkUpdates` | boolean | true | 启动时检查 CLI 更新 | ## 故障排除 MDX 文件会被解析为 JSX，因此某些字符具有特殊含义。 **常见问题：** `<` 字符会被解释为 JSX 标签的开始。 ```text ✗ Found 1 MDX syntax error(s) getting-started.mdx:42 Unexpected character `5` (U+0035) before name Fix: A < character is being parsed as JSX. Use < or rewrite ``` **解决方案：** - 对于字面量小于号，使用 `<`：`Values <50% are low` - 重写内容以避免使用该字符：使用 `"Below 50%"`，而不是 `"<50%"` - 运行 `jamdesk validate`，获取包含行号的详细错误消息确保当前位于包含 `docs.json` 文件的目录中。 **解决方案：** - 运行 `jamdesk init` 创建新项目 - 检查当前是否位于正确的目录 - 确认文件名必须准确为 `docs.json`（不能是 `doc.json` 或类似名称）开发服务器可能因多种原因无法启动。 **请尝试以下步骤：** 1. 运行 `jamdesk doctor` 检查环境 2. 运行 `jamdesk clean` 清除缓存 3. 使用 `jamdesk dev --verbose` 获取详细错误输出 4. 检查是否已安装 Node.js v20+：`node --version` 首次运行会将依赖项安装到 `~/.jamdesk/node_modules`。这是正常现象，只会发生一次。后续运行速度会快得多。另一个进程正在使用默认端口。 **解决方案：** ```bash # Use a different port jamdesk dev --port 3001 # Or set a default in ~/.jamdeskrc { "defaultPort": 3001 } ``` 你可能没有缓存目录的写入权限。 **解决方案：** 1. 检查 `~/.jamdesk` 的权限：`ls -la ~/.jamdesk` 2. 修复所有权：`sudo chown -R $(whoami) ~/.jamdesk` 3. 运行 `jamdesk clean`，然后重试 **问题仍未解决？** 请查看 [CLI 故障排除指南](/cn/help/troubleshooting/cli-issues)，或在 [GitHub](https://github.com/jamdesk/jamdesk-cli/issues) 上提交问题。 ## 接下来做什么？登录流程、会话和故障排除从终端进行部署高级本地开发选项从 Mintlify 或其他平台迁移