ITADN
Comfy-Org/docs
代码 动态 Issues69 合并请求293 版本
Comfy-Org/docs · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

ComfyUI 文档

| English | 中文 | 日本語 | 한국어 |

开发

要在本地预览文档更改，请先安装依赖项，然后启动开发服务器：

npm i
npm run dev

要同步编辑英文文档后的翻译，请参阅下文中的自动化翻译（npm run translate）。

创建 PR

创建一个 PR。一旦它被接受，Vercel 会将更改部署到 https://docs.comfy.org/

生成 API 参考文档

可以使用包含该文件的 OpenAPI 文件或 URL：

cd registry/api-reference # Keep API files separated by products.
npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>

这将仅为每个端点生成 MDX 文件。你需要在 docs.json 中添加指向这些文件的链接，该文档页面将显示最新的 API 规范。

关于重命名文件的特别说明

  • 重命名文件可能导致某些外部链接无法访问，因为它们已在众多文章和模板中使用。
  • 由于我们可以通过 docs.json 文件管理侧边栏导航并进行重新组织，除非绝对必要，否则我们通常不会更改原始文档的文件位置。
  • 如果你重命名了任何文件并导致文件路径发生变化，请更新 docs.json 中的 redirects 列表

GitHub Action 将检查重定向，如果缺少重定向，PR 将会失败。重定向应遵循以下格式：

"redirects": [
  {
    "source": "/path/to/old-file",
    "destination": "/path/to/new-file"
  }
]

别忘了在 zh/、ja/、ko/ 等目录下包含相应的翻译文件！

你也可以参考 Mintlify 文档 来学习如何添加和匹配通配符路径。

关于内置节点文档

ComfyUI 现在为内置节点和自定义节点都提供了内置节点帮助菜单。所有内置节点文档现在都将在 此仓库 中维护。

同步频率

我们将每周定期从相应仓库同步更新后的文档到 docs.comfy.org，以确保内容同步和更新。如果你希望为文档做出贡献，请向 此仓库 提交 PR 和更新。

节点文档文件组织

对于节点文档，我们将在 built-in-node 文件夹下使用单层目录结构，原因如下：

  • ComfyUI 可能会在更新期间调整节点类别和目录，使用多级目录层级意味着需要频繁调整节点文档
  • 这些频繁的调整意味着我们需要频繁添加重定向和检查
  • Mintlify 支持在 docs.json 文件中设置文档层级，因此我们可以在该文件中进行统一更改

由于历史更新，一些现有文档使用了不同的文件夹层级。我们将不再调整这些文件，但新文件将使用单层目录

贡献

请直接创建一个 PR，我们将在几天内对其进行审查。

或者在我们的 discord 上与我们交流

文档使用 Mintlify 构建，请参阅 Mintlify 文档 以了解如何使用它。

i18n 贡献

仓库根目录下的英文 MDX 是事实来源。翻译镜像语言目录下的相同相对路径（例如 zh/get_started/introduction.mdx、ja/get_started/introduction.mdx、ko/get_started/introduction.mdx）。可复用片段位于 snippets/，每个语言的副本位于 snippets/zh/、snippets/ja/、snippets/ko/ 等目录下。

其他语言的贡献指南：readme/ (中文, 日本語, 한국어).

翻译策略

支持的区域设置通过从英文进行的自动翻译来维护。当英文文档更改时，翻译将通过 npm run translate 批量更新——贡献者无需手动翻译每一页。

请求新语言

想要其他语言的文档？提交一个 issue，注明您需要的语言（例如法语、德语或巴西葡萄牙语）。维护者会将该语言添加到 translation-config.json 和 docs.json，然后对所有内容执行完整批量翻译。您只需提交请求即可；无需提交已翻译的 MDX PR 即可开始。

有关编辑 MDX 的规范，可在 Mintlify 文档的 Writing Content 部分中找到。

注意：built-in-nodes/ 在 embedded-docs 中维护，并且被翻译脚本跳过。请勿对该文件夹执行批量翻译。

自动翻译

此仓库包含一个基于哈希的翻译脚本。它将每个英文文件与存储在翻译文件中的 translationSourceHash 进行比较；当英文源文件发生变化时，该文件将被完全重新翻译。

先决条件

  1. Install Bun
  2. Copy the env template and add your API key:
cp .env.local.example .env.local
# Set TRANSLATE_API_KEY (OpenAI-compatible: DashScope Qwen-MT, OpenRouter, DeepSeek, etc.)

npm 脚本

命令描述
npm run translate翻译 translation-config.json 中列出的所有语言
npm run translate:dry-run列出待处理文件，不调用 API
npm run translate:force重新翻译所有内容，忽略已存储的哈希值
npm run translate:snippets仅翻译 snippets/
npm run translate:snippets:dry-run预览待处理的片段翻译
npm run translate:check-truncation扫描可能截断的翻译
npm run translate:repair-truncated重新翻译截断日志中列出的文件
npm run glossary:sync从 ComfyUI 前端重建术语表（参见 术语一致性)
npm run translate:review使用 AI 评审员对现有翻译进行评分（参见 质量审查)

在 -- 之后传递额外的标志：

npm run translate -- --lang zh,ja
npm run translate:dry-run -- --lang ja
npm run translate -- installation/manual_install.mdx
npm run translate:check-truncation -- --lang ko
npm run translate:repair-truncated -- --lang ko

截断的翻译

长文件偶尔会在翻译中途被截断（例如未闭合的代码围栏）。批量运行后，脚本会扫描新翻译的文件，并将修复列表写入 .github/i18n-logs/translate/truncation-issues.json 和 truncation-issues.txt（已加入 gitignore）。要扫描某种语言的所有文件，或进行修复：

npm run translate:check-truncation -- --lang ko
npm run translate:repair-truncated -- --lang ko

repair-truncated 读取 JSON 日志，并强制重新翻译被标记的文件。

工作原理

  • 输入：英文 MDX（主要）+ 现有目标语言文件作为上下文（如果存在）
  • 输出：位于 zh/、ja/、ko/ 等目录下的更新文件，frontmatter 中的 translationSourceHash 已刷新（片段使用 HTML 注释存储哈希值）
  • 审查备注（不匹配）：当模型通过 === MISMATCHES === 报告语义问题时，它们会写入 .github/i18n-logs/translate/mismatches.json 和 mismatches.txt（已被 gitignore 忽略），而不会写入 MDX。仅在 npm run translate 期间生成，截断扫描器不会生成。
  • 截断日志：结构问题（未闭合的代码围栏、正文过短）会记录到 .github/i18n-logs/translate/truncation-issues.json — 参见上文 Truncated translations。
  • 跳过路径：built-in-nodes/（在 translation-config.json → skip_paths 中配置）
  • 分块文件：changelog/index.mdx 由 <Update label="v0.x.x"> 版本标签处理。脚本比较英文与目标语言标签，仅翻译缺失的版本，并按英文顺序插入。除非使用 --force，否则旧块永远不会重新翻译。
  • 目录：写入文件时会自动创建子目录；您无需手动 mkdir

脚本位置：.github/scripts/i18n/（详见 translate-i18n.ts、translation-config.json 以及 i18n README）

术语一致性

为了确保相同的英文术语在不同页面中保持一致的译法（例如，避免 "custom node" 在两种不同的韩语翻译中产生偏差），有三种互补的机制为翻译器提供输入。每种机制处理不同类型的术语：

机制效果示例维护方式
preserve_terms（位于 translation-config.json 中）将术语保留为英文checkpoint、LoRA、scheduler手动维护
glossary/frontend/{lang}.json使用前端的翻译workflow → 워크플로机器同步
glossary/overrides/{lang}.json修正 / 扩展前端custom node → 커스텀 노드手动维护，优先级最高

ComfyUI 前端（ComfyUI_frontend/src/locales）是术语翻译的权威来源。npm run glossary:sync 将其本地化术语镜像到 glossary/frontend/{lang}.json（每次运行时整体重建——切勿手动编辑）。手动维护的修正位于 glossary/overrides/{lang}.json，其优先级高于镜像，是记录术语决策或移除前端中噪声术语的地方：

// glossary/overrides/ko.json
{
  "terms":  { "custom node": "커스텀 노드" },   // remap or add (wins over frontend)
  "ignore": ["title", "additional", "work"]      // drop a noisy frontend term
}

在翻译时，仅选择文档中实际出现的术语，并将其作为首选（而非强制）提示注入，以便在直译读起来生硬时，模型能保持自然的措辞。ComfyUI 中尚无定译的专有名词（模型名称、checkpoint、……）则保留在 preserve_terms 中以维持英文。有关完整的设计与策展指南，请参阅 i18n README。

npm run glossary:sync                 # rebuild the frontend mirror, all languages
npm run glossary:sync -- --lang ko    # one language
npm run glossary:sync:dry-run         # report counts without writing

前端语言源按以下顺序解析：

  • 远程（默认）： frontend_locales_url 位于 translation-config.json（GitHub raw main 分支）。可通过 FRONTEND_LOCALES_URL 或 --frontend-url <url> 覆盖。
  • 本地（可选）： 当需要离线或 fork 检出时，使用 --frontend <path> 或 FRONTEND_LOCALES_PATH。

质量审查

npm run translate:review 使用一个独立的（且通常更便宜的）AI 模型——即 LLM-as-a-judge——从四个维度对现有翻译进行评分：准确性、完整性、术语（对照术语表检查）和流畅度。它独立于翻译模型自身的 === MISMATCHES === 自注；在此，由另一个模型充当评审。

结果具有建议性：详细评分和问题列表写入 .github/i18n-logs/review/（quality-report.json / .txt，已加入 gitignore），且从不阻塞 PR。被审查的哈希值作为 reviewSourceHash 记录在翻译文件的 frontmatter 中（提交至 git），因此审查状态在团队间共享并按文件可见——与 translationSourceHash 保持一致。默认情况下，仅检查与英文保持最新且在该哈希下尚未审查的翻译。

npm run translate:review                     # pending reviews, all languages
npm run translate:review -- --lang ko        # one language
npm run translate:review -- --all            # re-review everything
npm run translate:review -- --sample 20      # N pending files per language
npm run translate:review -- --min-score 4    # report files scoring below 4/5

通过 REVIEW_API_KEY / REVIEW_API_BASE_URL / REVIEW_API_MODEL 在 .env.local 中配置专用的廉价评判模型（未设置时回退到 TRANSLATE_* 模型）。请使用快速模型——评估比翻译更轻量；推理密集型模型在并发下速度较慢，因此如果看到连接错误，请降低 REVIEW_CONCURRENCY。

添加新语言

参见上方 Request a new language — 请提交 issue，而不是在 PR 中自行添加语言。

维护者：在 .github/scripts/i18n/translation-config.json 的 languages 下添加一个条目（code、name、dir、snippets_dir）。路径排除、链接本地化和英文文件扫描由同一文件夹中的 i18n-config.mjs 自动派生——添加语言环境时无需编辑翻译脚本。然后在 docs.json 中添加导航（参见 Mintlify Localization），并批量翻译：

npm run glossary:sync -- --lang fr        # build the terminology glossary for the new locale
npm run translate:dry-run -- --lang fr
npm run translate -- --lang fr
npm run translate:snippets -- --lang fr

术语表会自动扩展：一旦语言位于 translation-config.json 中，npm run glossary:sync 就会从 ComfyUI 前端语言环境生成 glossary/frontend/{lang}.json（前提是前端提供了该语言环境）。glossary/overrides/{lang}.json 文件是可选的——仅在需要更正或固定特定术语时稍后添加。参见 术语一致性。

手动翻译

您也可以不使用脚本，而是手动进行翻译：

  1. 在语言目录下创建一个文件，其文件名和路径与英文原版相同。
  2. 本地化 import 路径（/snippets/... → /snippets/zh/...）和内部链接（/path → /zh/path）。
  3. 将页面路径添加到 docs.json 中正确的语言组。

当英文 MDX 发生变化时，i18n-sync-check 工作流会警告匹配的翻译文件是否未在同一 PR 中更新，并发布一条标记 @comfyui-wiki 的提醒评论。请手动更新翻译或重新运行 npm run translate。

贡献工作流示例

在向文档中添加工作流示例时，请：

  1. 获取来自 ComfyUI 的输出（PNG、WebP），并将模型 URL 添加到工作流中，以便用户在拖入工作流时拥有这些模型。您可以使用此 工具 来编辑 PNG 或 WebP 文件的元数据。

Video Title

  1. Upload your workflow JSON and preview image to the example_workflows repository
  2. Use the raw GitHub content URL in your documentation. To convert a GitHub file URL to a raw content URL:
    • Start with your GitHub file URL: 
      https://github.com/Comfy-Org/example_workflows/blob/main/your-workflow.json
    • Change it to raw.githubusercontent.com and remove '/blob': 
      https://raw.githubusercontent.com/Comfy-Org/example_workflows/main/your-workflow.json

您也可以点击 GitHub 文件页面上的 "Raw" 按钮，直接复制 URL。

这确保了将工作流拖入 ComfyUI 时，工作流元数据在文档站点中得以保留。