n8n 版本化节点Versioned Nodes全解析97 个多版本节点的版本数组清单与升级机制【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp导读n8n 通过版本化节点Versioned Nodes机制在同一个节点类型上维护多个接口版本从而在引入新特性、修复缺陷的同时保持对存量工作流的向后兼容。本篇文章以仓库根目录的 versioned-nodes.md 为骨架完整梳理 n8n-nodes-base 与 n8n/n8n-nodes-langchain 两个核心包中97 个以数组形式声明version的节点并结合本仓库n8n-mcp中的NodeVersionService、BreakingChangeDetector、parseTypeVersion等源码实现讲解版本数组的取值规则、版本比较算法、升级路径分析与破坏性变更检测的底层原理。读完本文你将能读懂任意 n8n 节点的version/defaultVersion字段判断工作流中某个节点是否过期并理解 AI 构建器如何自动完成节点的版本升级与迁移。一、什么是 n8n 的版本化节点在 n8n 中绝大多数节点的描述对象INodeTypeDescription都带有version字段。绝大多数节点只声明一个标量版本如version: 1而版本化节点则把version声明为一个数组例如// n8n-nodes-base 中的 Code 节点 version: [1, 2] // HTTP Request V3 节点 version: [3, 4, 4.1, 4.2] // Webhook 节点 version: [1, 1.1, 2]数组中的每一项代表该节点曾经或当前支持的一个类型版本typeVersion。运行时 n8n 依据工作流 JSON 中每个节点实例的typeVersion字段选择对应的节点实现来执行因此同一份工作流可以同时包含使用 v1 与 v2 的 Code 节点而互不干扰。从 versioned-nodes.md 的 Summary 可知全仓库共统计到97 个使用版本数组的节点来自n8n-nodes-base包65 个来自n8n/n8n-nodes-langchain包32 个版本数组模式带来的四项能力原文档归纳了版本数组设计的四个核心目的支持同一节点的多版本并存——不同版本可以拥有不同的属性结构、默认值和执行逻辑保持对存量工作流的向后兼容——老版本节点不会被强制删除旧工作流继续以旧版本运行在新版本中引入破坏性变更——新版本可以改变参数、必填项甚至行为同时让旧版本保持可用通过defaultVersion指定新实例的默认版本——当用户在界面上新建节点时默认落到哪个版本。二、n8n-nodes-base 包中的版本化节点完整清单65 个下表完整收录 versioned-nodes.md 中来自n8n-nodes-base包的 65 个版本化节点文件名列对应其在nodes目录下的实现文件#节点名称实现文件1AirtopAirtop.node.js2Cal TriggerCalTrigger.node.js3CodaCoda.node.js4CodeCode.node.jsversion: [1, 2]5Compare DatasetsCompareDatasets.node.js6CompressionCompression.node.js7Convert To FileConvertToFile.node.js8Email Send V2EmailSendV2.node.js9Execute WorkflowExecuteWorkflow.node.js10Execute Workflow TriggerExecuteWorkflowTrigger.node.js11Filter V2FilterV2.node.js12Form Trigger V2FormTriggerV2.node.js13GitHubGithub.node.js14Gmail TriggerGmailTrigger.node.js15Gmail V2GmailV2.node.js16Google BooksGoogleBooks.node.js17Google CalendarGoogleCalendar.node.js18Google DocsGoogleDocs.node.js19Google Drive V1GoogleDriveV1.node.js20Google Firebase Cloud FirestoreGoogleFirebaseCloudFirestore.node.js21Google SlidesGoogleSlides.node.js22Google TranslateGoogleTranslate.node.js23GraphQLGraphQL.node.js24HTMLHtml.node.js25HTTP Request V3HttpRequestV3.node.jsversion: [3, 4, 4.1, 4.2]26HubSpot V2HubspotV2.node.js27If V2IfV2.node.js28Invoice NinjaInvoiceNinja.node.js29Invoice Ninja TriggerInvoiceNinjaTrigger.node.js30Item Lists V2ItemListsV2.node.js31Jira TriggerJiraTrigger.node.js32Kafka TriggerKafkaTrigger.node.js33MailerLite Trigger V2MailerLiteTriggerV2.node.js34MailerLite V2MailerLiteV2.node.js35Merge V2MergeV2.node.js36Microsoft SQLMicrosoftSql.node.js37Microsoft Teams V1MicrosoftTeamsV1.node.js38MindeeMindee.node.js39MongoDBMongoDb.node.js40Move Binary DataMoveBinaryData.node.js41NocoDBNocoDB.node.js42OpenAIOpenAi.node.js43Pipedrive TriggerPipedriveTrigger.node.js44RabbitMQRabbitMQ.node.js45Remove Duplicates V1RemoveDuplicatesV1.node.js46Remove Duplicates V2RemoveDuplicatesV2.node.js47Respond To WebhookRespondToWebhook.node.js48RSS Feed ReadRssFeedRead.node.js49Schedule TriggerScheduleTrigger.node.js50Set V1SetV1.node.js51Set V2SetV2.node.js52Slack V2SlackV2.node.js53StravaStrava.node.js54SummarizeSummarize.node.js55Switch V1SwitchV1.node.js56Switch V2SwitchV2.node.js57Switch V3SwitchV3.node.js58TelegramTelegram.node.js59Telegram TriggerTelegramTrigger.node.js60The Hive TriggerTheHiveTrigger.node.js61Todoist V2TodoistV2.node.js62Twilio TriggerTwilioTrigger.node.js63Typeform TriggerTypeformTrigger.node.js64WaitWait.node.js65WebhookWebhook.node.jsversion: [1, 1.1, 2]从清单可以观察到两个规律其一版本化节点大量集中在触发类节点Trigger与核心流程控制节点Set、Switch、Merge、If、Filter、Wait 等上因为它们承载了最多的工作流兼容性诉求其二文件名中带 V1/V2/V3 后缀的节点通常其内部version数组与文件名主版本号一致如SwitchV1/V2/V3分别对应版本 1、2、3而SetV2实际声明的版本从 3 起步见下文示例说明文件名后缀与 typeVersion 并不总是严格一一对应。三、n8n/n8n-nodes-langchain 包中的版本化节点完整清单32 个随着 n8n 内置 LangChain 生态AI 相关节点同样大规模采用了版本数组。下表为 versioned-nodes.md 收录的 32 个节点#节点名称实现文件1Agent V1AgentV1.node.js2Chain LLMChainLlm.node.js3Chain Retrieval QAChainRetrievalQa.node.js4Chain Summarization V2ChainSummarizationV2.node.js5Chat TriggerChatTrigger.node.js6Document Default Data LoaderDocumentDefaultDataLoader.node.js7Document GitHub LoaderDocumentGithubLoader.node.js8Embeddings OpenAIEmbeddingsOpenAi.node.js9Information ExtractorInformationExtractor.node.js10LM Chat AnthropicLmChatAnthropic.node.js11LM Chat DeepSeekLmChatDeepSeek.node.js12LM Chat OpenAILmChatOpenAi.node.js13LM Chat OpenRouterLmChatOpenRouter.node.js14LM Chat xAI GrokLmChatXAiGrok.node.js15Manual Chat TriggerManualChatTrigger.node.js16MCP TriggerMcpTrigger.node.js17Memory Buffer WindowMemoryBufferWindow.node.js18Memory ManagerMemoryManager.node.js19Memory MongoDB ChatMemoryMongoDbChat.node.js20Memory MotorheadMemoryMotorhead.node.js21Memory Postgres ChatMemoryPostgresChat.node.js22Memory Redis ChatMemoryRedisChat.node.js23Memory XataMemoryXata.node.js24Memory ZepMemoryZep.node.js25OpenAI AssistantOpenAiAssistant.node.js26Output Parser StructuredOutputParserStructured.node.js27Retriever WorkflowRetrieverWorkflow.node.js28Sentiment AnalysisSentimentAnalysis.node.js29Text ClassifierTextClassifier.node.js30Tool CodeToolCode.node.js31Tool HTTP RequestToolHttpRequest.node.js32Tool Vector StoreToolVectorStore.node.jsLangChain 包中的节点呈现三个特点大模型聊天类LM Chat节点高度碎片化版本几乎每个厂商一个实现文件版本数组普遍较长记忆类Memory节点密集多达 8 种后端实现Agent / Chain / Tool 类节点版本演进最活跃其中 Chain LLM 是全部 97 个节点中版本数最多的一个。四、真实版本数组示例与版本模式分类4.1 n8n-nodes-base 中的代表性示例原文档给出了 7 个实际从节点源码中提取的版本数组// Code version: [1, 2] // HTTP Request V3 version: [3, 4, 4.1, 4.2] // Webhook version: [1, 1.1, 2] // Wait version: [1, 1.1] // Schedule Trigger version: [1, 1.1, 1.2] // Switch V3 version: [3, 3.1, 3.2] // Set V2 version: [3, 3.1, 3.2, 3.3, 3.4]4.2 n8n/n8n-nodes-langchain 中的代表性示例// LM Chat OpenAI version: [1, 1.1, 1.2] // Chain LLM —— 全仓库版本数最多的节点 version: [1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7] // Tool HTTP Request version: [1, 1.1]4.3 四种常见版本模式原文档将观察到的版本数组归纳为四类模式示例说明简单递增Simple incremental[1, 2]、[1, 2, 3]主版本号推进通常伴随破坏性变更次版本Minor versions[1, 1.1, 1.2]常见于缺陷修复与参数微调一般向后兼容补丁版本Patch versions[3, 4, 4.1, 4.2]细粒度版本追踪同一大版本下多次迭代扩展版本Extended versions[1, 1.1, …, 1.7]长生命周期节点的持续演进Chain LLM 为典型4.4 关键认知文件名后缀 ≠ typeVersion注意Set V2的版本数组是[3, 3.1, 3.2, 3.3, 3.4]而Switch V3是[3, 3.1, 3.2]。这印证了前文观点实现文件的命名后缀V2/V3只是文件组织约定真正决定运行时行为的字段是描述对象里的version数组与每个节点实例上的typeVersion。在编写或校验工作流 JSON 时应以节点描述中的版本数组为准而不是凭文件名猜测。五、源码级支撑n8n-mcp 如何理解与利用节点版本versioned-nodes.md不仅是一份静态清单它还直接服务于本仓库n8n-mcp的节点版本管理能力。下面结合源码说明这条数据链路是如何被打通的。5.1 版本数据的入库与查询节点版本信息被持久化在node_versions表中由 src/database/node-repository.ts 提供存取getNodeVersions(nodeType)按node_type查询全部版本按版本倒序返回node-repository.ts 中 getNodeVersionsgetLatestNodeVersion(nodeType)按is_current_max 1标记查询当前最新版本node-repository.ts 中 getLatestNodeVersiongetNodeVersion(nodeType, version)精确查询某个具体版本node-repository.ts 中 getNodeVersion。每个版本行还携带minimum_n8n_version最低运行版本、breaking_changes、deprecated_properties、added_properties、properties_schema等元数据为后续的版本分析与升级建议提供数据基础见 node-repository.ts 的版本保存逻辑。5.2 版本解析parseTypeVersion与isValidTypeVersion运行时version字段可能以多种形态出现数字、数字数组、SQLite 存储后的字符串如1,2、JSON 数组字符串如[1, 2]。src/utils/typeversion.ts 中的parseTypeVersion统一处理这些形态// 输入number、number[]、string含 1,2 与 [1, 2] // 输出数组取最大值后的数字版本无法解析时返回 null parseTypeVersion([1, 1.1, 1.2]) // 1.2 parseTypeVersion(1,2) // 2 parseTypeVersion([1, 2]) // 2该函数有一个值得注意的边界处理显式拒绝多段点号分隔的 npm 包版本字符串如0.2.21、2.1.17-rc.31因为它们不是合法的 typeVersion直接Number()会得到NaN从而静默破坏版本比较逻辑。配套的isValidTypeVersion则要求必须是有限且非负的 numbertypeVersion 0 也是合法值这一约定与工作流校验器的类型检查保持一致见 typeversion.ts 的实现注释与代码。5.3 版本服务NodeVersionServicesrc/services/node-version-service.ts 是版本能力的核心服务提供以下关键能力版本发现与缓存getAvailableVersions(nodeType)先查 5 分钟 TTL 的内存缓存未命中才回源数据库getLatestVersion优先取标记为isCurrentMax的版本否则回退到版本排序取最大值node-version-service.ts 中 getLatestVersion。版本比较算法compareVersions将版本按.拆分为数字段后逐位比较缺位补 0。因此compareVersions(1.0, 1.0.0) 0compareVersions(2, 1.9) 1——这与 n8n 实际使用的 typeVersion 语义如 1、1.1、1.2 这类十进制小版本完全吻合node-version-service.ts 中 compareVersions。过期分析analyzeVersion(nodeType, currentVersion)返回VersionComparison结构包含isOutdated、versionGap版本差距、hasBreakingChanges、recommendUpgrade与三档confidenceHIGH / MEDIUM / LOW。规则如下见 node-version-service.ts 中 analyzeVersion无版本信息或已是最高版本 →HIGH置信度不推荐升级存在破坏性变更 → 置信度降为MEDIUM提示升级前需审查版本差距大于 2 → 置信度降为LOW建议分步增量升级。升级路径规划suggestUpgradePath(nodeType, currentVersion)结合BreakingChangeDetector.analyzeVersionUpgrade生成逐步升级方案UpgradePath当差距小或无破坏性变更时走直接升级否则在中间版本间逐段规划并汇总totalBreakingChanges、autoMigratableChanges、manualRequiredChanges最终给出LOW / MEDIUM / HIGH三档工作量评估node-version-service.ts 中 suggestUpgradePath。5.4 破坏性变更检测BreakingChangeDetector与注册表升级建议的可靠性取决于破坏性变更的检测精度。src/services/breaking-change-detector.ts 通过两条路径检测变更见其头注释与analyzeVersionUpgrade实现注册表路径registry查询 src/services/breaking-changes-registry.ts 中硬编码的BREAKING_CHANGES_REGISTRY。该注册表记录了每个已知变更的属性名、变更类型added / removed / renamed / type_changed / requirement_changed / default_changed、是否破坏性、迁移提示与迁移策略。例如// Execute Workflow v1.0 → v1.1新增必填的 inputFieldMapping { nodeType: n8n-nodes-base.executeWorkflow, fromVersion: 1.0, toVersion: 1.1, propertyName: parameters.inputFieldMapping, changeType: added, isBreaking: true, autoMigratable: true, migrationStrategy: { type: add_property, defaultValue: { mappings: [] } }, severity: HIGH } // Webhook v2.0 → v2.1新增唯一 webhookId { nodeType: n8n-nodes-base.webhook, fromVersion: 2.0, toVersion: 2.1, propertyName: webhookId, changeType: added, isBreaking: true, autoMigratable: true, migrationStrategy: { type: add_property, defaultValue: null } // 运行时自动生成 UUID }动态路径dynamic对两个版本的properties_schema做结构比对自动发现属性新增、删除、重命名、类型变化、必填性变化与默认值变化并为其标注是否可自动迁移。两条路径的变更会被合并去重mergeChanges最终汇总出autoMigratableCount / manualRequiredCount / overallSeverity / recommendations供上层使用。5.5 自动修复器中的落地typeversion-upgrade与version-migration在 src/services/workflow-auto-fixer.ts 中版本能力被编排进 AI 工作流自动修复流水线修复类型枚举中包含typeversion-correction版本号纠错、typeversion-upgrade主动升级到最新版与version-migration带破坏性变更的智能迁移workflow-auto-fixer.ts 的 FixType 定义当工作流校验报错typeVersion N exceeds maximum supported version M时自动修复器会从错误消息中解析当前版本与最大支持版本执行版本回退修正workflow-auto-fixer.ts 的错误解析逻辑主动升级流程调用versionService.analyzeVersion对每个节点做过期分析并对recommendUpgrade的节点生成升级修复迁移流程则针对version-migration类型利用suggestUpgradePath的输出生成多步迁移方案workflow-auto-fixer.ts 的版本升级处理。5.6 测试验证上述行为有完整的单元测试覆盖见 tests/unit/services/node-version-service.test.ts包括缓存行为TTL 内只回源一次越过 5 分钟 TTL 后重新查询clearCache可针对单个节点或全量清空对应getAvailableVersions测试组版本比较边界1.0vs1.0.0相等、1.0vs1.0.1为低、2vs1.9为高、0.0.0vs0.0.1为低、1vs2为低compareVersions测试组升级建议直接升级direct: true、单步与多步升级intermediateVersions包含中间版本、工作量从 LOW 到 HIGH 的判定suggestUpgradePath测试组。六、对 AI 工作流构建者的实践建议读取节点描述而非文件名判断一个节点支持的版本范围以version数组和defaultVersion为准。例如 AI 构建器在生成工作流时应为新节点写入节点描述中defaultVersion对应的版本参见 src/parsers/node-parser.ts 中 extractVersion 的优先级逻辑它依次检查实例description.defaultVersion→nodeVersions最大值 → 描述版本数组最大值。理解typeVersion是工作流的一部分工作流 JSON 中每个节点的typeVersion决定其行为。迁移工作流时直接修改typeVersion而不核对破坏性变更可能导致参数校验失败应借助suggestUpgradePath与BREAKING_CHANGES_REGISTRY做分步迁移。善用版本差距与置信度信号当analyzeVersion返回LOW置信度版本差距大或MEDIUM置信度含破坏性变更时应保守处理——优先选择逐版本升级并逐段验证而不是一次性跳到最新版。警惕字符串形态的版本数据在 SQLite 存储或跨系统传输场景中版本字段可能以1,2、[1, 2]等字符串形态出现务必经由parseTypeVersion归一化后再参与比较同时避免把 npm 包版本字符串误当作 typeVersion。七、总结全仓库共97 个节点使用版本数组声明多版本支持n8n-nodes-base 65 个、n8n/n8n-nodes-langchain 32 个版本数组模式的核心价值是多版本并存、向后兼容、新版本可引入破坏性变更、defaultVersion控制新实例默认版本常见版本模式包括简单递增[1, 2]、次版本[1, 1.1, 1.2]、补丁版本[3, 4, 4.1, 4.2]与扩展版本Chain LLM 的[1 … 1.7]本仓库n8n-mcp通过 node-repository.ts 持久化版本元数据由 node-version-service.ts 提供发现、比较、过期分析与升级路径规划由 breaking-change-detector.ts 与 breaking-changes-registry.ts 负责破坏性变更检测最终在 workflow-auto-fixer.ts 中落地为自动化的版本升级与迁移修复。对开发者而言理解这份 97 节点的版本清单及其背后的实现链路等于掌握了 n8n 节点兼容性体系的地图——无论是手工维护存量工作流还是构建 AI 辅助的工作流生成/修复工具都能据此做出安全、可验证的版本决策。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
n8n 版本化节点（Versioned Nodes）全解析：97 个多版本节点的版本数组清单与升级机制
n8n 版本化节点Versioned Nodes全解析97 个多版本节点的版本数组清单与升级机制【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp导读n8n 通过版本化节点Versioned Nodes机制在同一个节点类型上维护多个接口版本从而在引入新特性、修复缺陷的同时保持对存量工作流的向后兼容。本篇文章以仓库根目录的 versioned-nodes.md 为骨架完整梳理 n8n-nodes-base 与 n8n/n8n-nodes-langchain 两个核心包中97 个以数组形式声明version的节点并结合本仓库n8n-mcp中的NodeVersionService、BreakingChangeDetector、parseTypeVersion等源码实现讲解版本数组的取值规则、版本比较算法、升级路径分析与破坏性变更检测的底层原理。读完本文你将能读懂任意 n8n 节点的version/defaultVersion字段判断工作流中某个节点是否过期并理解 AI 构建器如何自动完成节点的版本升级与迁移。一、什么是 n8n 的版本化节点在 n8n 中绝大多数节点的描述对象INodeTypeDescription都带有version字段。绝大多数节点只声明一个标量版本如version: 1而版本化节点则把version声明为一个数组例如// n8n-nodes-base 中的 Code 节点 version: [1, 2] // HTTP Request V3 节点 version: [3, 4, 4.1, 4.2] // Webhook 节点 version: [1, 1.1, 2]数组中的每一项代表该节点曾经或当前支持的一个类型版本typeVersion。运行时 n8n 依据工作流 JSON 中每个节点实例的typeVersion字段选择对应的节点实现来执行因此同一份工作流可以同时包含使用 v1 与 v2 的 Code 节点而互不干扰。从 versioned-nodes.md 的 Summary 可知全仓库共统计到97 个使用版本数组的节点来自n8n-nodes-base包65 个来自n8n/n8n-nodes-langchain包32 个版本数组模式带来的四项能力原文档归纳了版本数组设计的四个核心目的支持同一节点的多版本并存——不同版本可以拥有不同的属性结构、默认值和执行逻辑保持对存量工作流的向后兼容——老版本节点不会被强制删除旧工作流继续以旧版本运行在新版本中引入破坏性变更——新版本可以改变参数、必填项甚至行为同时让旧版本保持可用通过defaultVersion指定新实例的默认版本——当用户在界面上新建节点时默认落到哪个版本。二、n8n-nodes-base 包中的版本化节点完整清单65 个下表完整收录 versioned-nodes.md 中来自n8n-nodes-base包的 65 个版本化节点文件名列对应其在nodes目录下的实现文件#节点名称实现文件1AirtopAirtop.node.js2Cal TriggerCalTrigger.node.js3CodaCoda.node.js4CodeCode.node.jsversion: [1, 2]5Compare DatasetsCompareDatasets.node.js6CompressionCompression.node.js7Convert To FileConvertToFile.node.js8Email Send V2EmailSendV2.node.js9Execute WorkflowExecuteWorkflow.node.js10Execute Workflow TriggerExecuteWorkflowTrigger.node.js11Filter V2FilterV2.node.js12Form Trigger V2FormTriggerV2.node.js13GitHubGithub.node.js14Gmail TriggerGmailTrigger.node.js15Gmail V2GmailV2.node.js16Google BooksGoogleBooks.node.js17Google CalendarGoogleCalendar.node.js18Google DocsGoogleDocs.node.js19Google Drive V1GoogleDriveV1.node.js20Google Firebase Cloud FirestoreGoogleFirebaseCloudFirestore.node.js21Google SlidesGoogleSlides.node.js22Google TranslateGoogleTranslate.node.js23GraphQLGraphQL.node.js24HTMLHtml.node.js25HTTP Request V3HttpRequestV3.node.jsversion: [3, 4, 4.1, 4.2]26HubSpot V2HubspotV2.node.js27If V2IfV2.node.js28Invoice NinjaInvoiceNinja.node.js29Invoice Ninja TriggerInvoiceNinjaTrigger.node.js30Item Lists V2ItemListsV2.node.js31Jira TriggerJiraTrigger.node.js32Kafka TriggerKafkaTrigger.node.js33MailerLite Trigger V2MailerLiteTriggerV2.node.js34MailerLite V2MailerLiteV2.node.js35Merge V2MergeV2.node.js36Microsoft SQLMicrosoftSql.node.js37Microsoft Teams V1MicrosoftTeamsV1.node.js38MindeeMindee.node.js39MongoDBMongoDb.node.js40Move Binary DataMoveBinaryData.node.js41NocoDBNocoDB.node.js42OpenAIOpenAi.node.js43Pipedrive TriggerPipedriveTrigger.node.js44RabbitMQRabbitMQ.node.js45Remove Duplicates V1RemoveDuplicatesV1.node.js46Remove Duplicates V2RemoveDuplicatesV2.node.js47Respond To WebhookRespondToWebhook.node.js48RSS Feed ReadRssFeedRead.node.js49Schedule TriggerScheduleTrigger.node.js50Set V1SetV1.node.js51Set V2SetV2.node.js52Slack V2SlackV2.node.js53StravaStrava.node.js54SummarizeSummarize.node.js55Switch V1SwitchV1.node.js56Switch V2SwitchV2.node.js57Switch V3SwitchV3.node.js58TelegramTelegram.node.js59Telegram TriggerTelegramTrigger.node.js60The Hive TriggerTheHiveTrigger.node.js61Todoist V2TodoistV2.node.js62Twilio TriggerTwilioTrigger.node.js63Typeform TriggerTypeformTrigger.node.js64WaitWait.node.js65WebhookWebhook.node.jsversion: [1, 1.1, 2]从清单可以观察到两个规律其一版本化节点大量集中在触发类节点Trigger与核心流程控制节点Set、Switch、Merge、If、Filter、Wait 等上因为它们承载了最多的工作流兼容性诉求其二文件名中带 V1/V2/V3 后缀的节点通常其内部version数组与文件名主版本号一致如SwitchV1/V2/V3分别对应版本 1、2、3而SetV2实际声明的版本从 3 起步见下文示例说明文件名后缀与 typeVersion 并不总是严格一一对应。三、n8n/n8n-nodes-langchain 包中的版本化节点完整清单32 个随着 n8n 内置 LangChain 生态AI 相关节点同样大规模采用了版本数组。下表为 versioned-nodes.md 收录的 32 个节点#节点名称实现文件1Agent V1AgentV1.node.js2Chain LLMChainLlm.node.js3Chain Retrieval QAChainRetrievalQa.node.js4Chain Summarization V2ChainSummarizationV2.node.js5Chat TriggerChatTrigger.node.js6Document Default Data LoaderDocumentDefaultDataLoader.node.js7Document GitHub LoaderDocumentGithubLoader.node.js8Embeddings OpenAIEmbeddingsOpenAi.node.js9Information ExtractorInformationExtractor.node.js10LM Chat AnthropicLmChatAnthropic.node.js11LM Chat DeepSeekLmChatDeepSeek.node.js12LM Chat OpenAILmChatOpenAi.node.js13LM Chat OpenRouterLmChatOpenRouter.node.js14LM Chat xAI GrokLmChatXAiGrok.node.js15Manual Chat TriggerManualChatTrigger.node.js16MCP TriggerMcpTrigger.node.js17Memory Buffer WindowMemoryBufferWindow.node.js18Memory ManagerMemoryManager.node.js19Memory MongoDB ChatMemoryMongoDbChat.node.js20Memory MotorheadMemoryMotorhead.node.js21Memory Postgres ChatMemoryPostgresChat.node.js22Memory Redis ChatMemoryRedisChat.node.js23Memory XataMemoryXata.node.js24Memory ZepMemoryZep.node.js25OpenAI AssistantOpenAiAssistant.node.js26Output Parser StructuredOutputParserStructured.node.js27Retriever WorkflowRetrieverWorkflow.node.js28Sentiment AnalysisSentimentAnalysis.node.js29Text ClassifierTextClassifier.node.js30Tool CodeToolCode.node.js31Tool HTTP RequestToolHttpRequest.node.js32Tool Vector StoreToolVectorStore.node.jsLangChain 包中的节点呈现三个特点大模型聊天类LM Chat节点高度碎片化版本几乎每个厂商一个实现文件版本数组普遍较长记忆类Memory节点密集多达 8 种后端实现Agent / Chain / Tool 类节点版本演进最活跃其中 Chain LLM 是全部 97 个节点中版本数最多的一个。四、真实版本数组示例与版本模式分类4.1 n8n-nodes-base 中的代表性示例原文档给出了 7 个实际从节点源码中提取的版本数组// Code version: [1, 2] // HTTP Request V3 version: [3, 4, 4.1, 4.2] // Webhook version: [1, 1.1, 2] // Wait version: [1, 1.1] // Schedule Trigger version: [1, 1.1, 1.2] // Switch V3 version: [3, 3.1, 3.2] // Set V2 version: [3, 3.1, 3.2, 3.3, 3.4]4.2 n8n/n8n-nodes-langchain 中的代表性示例// LM Chat OpenAI version: [1, 1.1, 1.2] // Chain LLM —— 全仓库版本数最多的节点 version: [1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7] // Tool HTTP Request version: [1, 1.1]4.3 四种常见版本模式原文档将观察到的版本数组归纳为四类模式示例说明简单递增Simple incremental[1, 2]、[1, 2, 3]主版本号推进通常伴随破坏性变更次版本Minor versions[1, 1.1, 1.2]常见于缺陷修复与参数微调一般向后兼容补丁版本Patch versions[3, 4, 4.1, 4.2]细粒度版本追踪同一大版本下多次迭代扩展版本Extended versions[1, 1.1, …, 1.7]长生命周期节点的持续演进Chain LLM 为典型4.4 关键认知文件名后缀 ≠ typeVersion注意Set V2的版本数组是[3, 3.1, 3.2, 3.3, 3.4]而Switch V3是[3, 3.1, 3.2]。这印证了前文观点实现文件的命名后缀V2/V3只是文件组织约定真正决定运行时行为的字段是描述对象里的version数组与每个节点实例上的typeVersion。在编写或校验工作流 JSON 时应以节点描述中的版本数组为准而不是凭文件名猜测。五、源码级支撑n8n-mcp 如何理解与利用节点版本versioned-nodes.md不仅是一份静态清单它还直接服务于本仓库n8n-mcp的节点版本管理能力。下面结合源码说明这条数据链路是如何被打通的。5.1 版本数据的入库与查询节点版本信息被持久化在node_versions表中由 src/database/node-repository.ts 提供存取getNodeVersions(nodeType)按node_type查询全部版本按版本倒序返回node-repository.ts 中 getNodeVersionsgetLatestNodeVersion(nodeType)按is_current_max 1标记查询当前最新版本node-repository.ts 中 getLatestNodeVersiongetNodeVersion(nodeType, version)精确查询某个具体版本node-repository.ts 中 getNodeVersion。每个版本行还携带minimum_n8n_version最低运行版本、breaking_changes、deprecated_properties、added_properties、properties_schema等元数据为后续的版本分析与升级建议提供数据基础见 node-repository.ts 的版本保存逻辑。5.2 版本解析parseTypeVersion与isValidTypeVersion运行时version字段可能以多种形态出现数字、数字数组、SQLite 存储后的字符串如1,2、JSON 数组字符串如[1, 2]。src/utils/typeversion.ts 中的parseTypeVersion统一处理这些形态// 输入number、number[]、string含 1,2 与 [1, 2] // 输出数组取最大值后的数字版本无法解析时返回 null parseTypeVersion([1, 1.1, 1.2]) // 1.2 parseTypeVersion(1,2) // 2 parseTypeVersion([1, 2]) // 2该函数有一个值得注意的边界处理显式拒绝多段点号分隔的 npm 包版本字符串如0.2.21、2.1.17-rc.31因为它们不是合法的 typeVersion直接Number()会得到NaN从而静默破坏版本比较逻辑。配套的isValidTypeVersion则要求必须是有限且非负的 numbertypeVersion 0 也是合法值这一约定与工作流校验器的类型检查保持一致见 typeversion.ts 的实现注释与代码。5.3 版本服务NodeVersionServicesrc/services/node-version-service.ts 是版本能力的核心服务提供以下关键能力版本发现与缓存getAvailableVersions(nodeType)先查 5 分钟 TTL 的内存缓存未命中才回源数据库getLatestVersion优先取标记为isCurrentMax的版本否则回退到版本排序取最大值node-version-service.ts 中 getLatestVersion。版本比较算法compareVersions将版本按.拆分为数字段后逐位比较缺位补 0。因此compareVersions(1.0, 1.0.0) 0compareVersions(2, 1.9) 1——这与 n8n 实际使用的 typeVersion 语义如 1、1.1、1.2 这类十进制小版本完全吻合node-version-service.ts 中 compareVersions。过期分析analyzeVersion(nodeType, currentVersion)返回VersionComparison结构包含isOutdated、versionGap版本差距、hasBreakingChanges、recommendUpgrade与三档confidenceHIGH / MEDIUM / LOW。规则如下见 node-version-service.ts 中 analyzeVersion无版本信息或已是最高版本 →HIGH置信度不推荐升级存在破坏性变更 → 置信度降为MEDIUM提示升级前需审查版本差距大于 2 → 置信度降为LOW建议分步增量升级。升级路径规划suggestUpgradePath(nodeType, currentVersion)结合BreakingChangeDetector.analyzeVersionUpgrade生成逐步升级方案UpgradePath当差距小或无破坏性变更时走直接升级否则在中间版本间逐段规划并汇总totalBreakingChanges、autoMigratableChanges、manualRequiredChanges最终给出LOW / MEDIUM / HIGH三档工作量评估node-version-service.ts 中 suggestUpgradePath。5.4 破坏性变更检测BreakingChangeDetector与注册表升级建议的可靠性取决于破坏性变更的检测精度。src/services/breaking-change-detector.ts 通过两条路径检测变更见其头注释与analyzeVersionUpgrade实现注册表路径registry查询 src/services/breaking-changes-registry.ts 中硬编码的BREAKING_CHANGES_REGISTRY。该注册表记录了每个已知变更的属性名、变更类型added / removed / renamed / type_changed / requirement_changed / default_changed、是否破坏性、迁移提示与迁移策略。例如// Execute Workflow v1.0 → v1.1新增必填的 inputFieldMapping { nodeType: n8n-nodes-base.executeWorkflow, fromVersion: 1.0, toVersion: 1.1, propertyName: parameters.inputFieldMapping, changeType: added, isBreaking: true, autoMigratable: true, migrationStrategy: { type: add_property, defaultValue: { mappings: [] } }, severity: HIGH } // Webhook v2.0 → v2.1新增唯一 webhookId { nodeType: n8n-nodes-base.webhook, fromVersion: 2.0, toVersion: 2.1, propertyName: webhookId, changeType: added, isBreaking: true, autoMigratable: true, migrationStrategy: { type: add_property, defaultValue: null } // 运行时自动生成 UUID }动态路径dynamic对两个版本的properties_schema做结构比对自动发现属性新增、删除、重命名、类型变化、必填性变化与默认值变化并为其标注是否可自动迁移。两条路径的变更会被合并去重mergeChanges最终汇总出autoMigratableCount / manualRequiredCount / overallSeverity / recommendations供上层使用。5.5 自动修复器中的落地typeversion-upgrade与version-migration在 src/services/workflow-auto-fixer.ts 中版本能力被编排进 AI 工作流自动修复流水线修复类型枚举中包含typeversion-correction版本号纠错、typeversion-upgrade主动升级到最新版与version-migration带破坏性变更的智能迁移workflow-auto-fixer.ts 的 FixType 定义当工作流校验报错typeVersion N exceeds maximum supported version M时自动修复器会从错误消息中解析当前版本与最大支持版本执行版本回退修正workflow-auto-fixer.ts 的错误解析逻辑主动升级流程调用versionService.analyzeVersion对每个节点做过期分析并对recommendUpgrade的节点生成升级修复迁移流程则针对version-migration类型利用suggestUpgradePath的输出生成多步迁移方案workflow-auto-fixer.ts 的版本升级处理。5.6 测试验证上述行为有完整的单元测试覆盖见 tests/unit/services/node-version-service.test.ts包括缓存行为TTL 内只回源一次越过 5 分钟 TTL 后重新查询clearCache可针对单个节点或全量清空对应getAvailableVersions测试组版本比较边界1.0vs1.0.0相等、1.0vs1.0.1为低、2vs1.9为高、0.0.0vs0.0.1为低、1vs2为低compareVersions测试组升级建议直接升级direct: true、单步与多步升级intermediateVersions包含中间版本、工作量从 LOW 到 HIGH 的判定suggestUpgradePath测试组。六、对 AI 工作流构建者的实践建议读取节点描述而非文件名判断一个节点支持的版本范围以version数组和defaultVersion为准。例如 AI 构建器在生成工作流时应为新节点写入节点描述中defaultVersion对应的版本参见 src/parsers/node-parser.ts 中 extractVersion 的优先级逻辑它依次检查实例description.defaultVersion→nodeVersions最大值 → 描述版本数组最大值。理解typeVersion是工作流的一部分工作流 JSON 中每个节点的typeVersion决定其行为。迁移工作流时直接修改typeVersion而不核对破坏性变更可能导致参数校验失败应借助suggestUpgradePath与BREAKING_CHANGES_REGISTRY做分步迁移。善用版本差距与置信度信号当analyzeVersion返回LOW置信度版本差距大或MEDIUM置信度含破坏性变更时应保守处理——优先选择逐版本升级并逐段验证而不是一次性跳到最新版。警惕字符串形态的版本数据在 SQLite 存储或跨系统传输场景中版本字段可能以1,2、[1, 2]等字符串形态出现务必经由parseTypeVersion归一化后再参与比较同时避免把 npm 包版本字符串误当作 typeVersion。七、总结全仓库共97 个节点使用版本数组声明多版本支持n8n-nodes-base 65 个、n8n/n8n-nodes-langchain 32 个版本数组模式的核心价值是多版本并存、向后兼容、新版本可引入破坏性变更、defaultVersion控制新实例默认版本常见版本模式包括简单递增[1, 2]、次版本[1, 1.1, 1.2]、补丁版本[3, 4, 4.1, 4.2]与扩展版本Chain LLM 的[1 … 1.7]本仓库n8n-mcp通过 node-repository.ts 持久化版本元数据由 node-version-service.ts 提供发现、比较、过期分析与升级路径规划由 breaking-change-detector.ts 与 breaking-changes-registry.ts 负责破坏性变更检测最终在 workflow-auto-fixer.ts 中落地为自动化的版本升级与迁移修复。对开发者而言理解这份 97 节点的版本清单及其背后的实现链路等于掌握了 n8n 节点兼容性体系的地图——无论是手工维护存量工作流还是构建 AI 辅助的工作流生成/修复工具都能据此做出安全、可验证的版本决策。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
