欢迎来到翔宇工作流的 n8n 深度教程系列！我是翔宇，接下来将担任你的自动化向导。

你是否常常觉得，处理数据听起来就像一项需要编程技能的复杂任务？n8n 的出现彻底改变了这种看法。你可以把它想象成一个功能强大的数字乐高积木盒子。通过简单地拖拽、连接不同的功能模块（n8n 中称之为“节点” Node），你就能搭建起自动化流程，处理各种数据的转换、整理和传输 。这使得自动化不再是程序员的专利，每个人都可以利用它来提升效率。

在这个教程中，我们专注于实践和理解，尽量避免深入复杂的代码。翔宇将一步步引导你，深入了解 n8n 中几个非常核心且实用的数据处理节点。学完之后，相信你也能自信地运用 n8n 来处理日常工作中的数据，成为数据整理、转换和比较的小能手。

在正式开始探索各个节点之前，翔宇必须强调一个基础但至关重要的概念：理解数据在 n8n 中是如何流动和组织的。这一点对于后续顺畅地使用各个节点至关重要，即使你完全不打算编写代码。想象一下，你的工作流就像一条处理流水线，数据以“项目” (Item) 的形式在这条线上传递。你可以把每个 Item 看作一个标准化的包裹。每个包裹（Item）内部，都有一个固定格式的清单，这个清单被称为 json 对象，里面存放着具体的货物信息（也就是你的数据，以键值对 Key-Value Pair 的形式存在）。节点（Node）就是流水线上的不同站点，它们接收这些包裹，按照你的指令对包裹里的清单 (json 对象) 进行处理，然后将处理后的包裹传递给下一个站点 。n8n 中的数据流通常是一个包含多个这种包裹（Item）的列表（技术上称为数组 Array）。理解了这个“包裹清单” (Item 包含 json 对象) 的基本结构，你就能更轻松地配置节点，告诉它们去哪里查找信息，以及如何修改信息。很多初学者遇到的问题，往往源于未能准确地指定数据在包裹中的位置 。记住这个基础模型，后面的学习将会事半功倍。

五个数据处理利器

本次教程，我们将聚焦于 n8n 内置核心节点库 (Core Nodes) 中的五个数据处理“利器”：

1. ​排序 (Sort)​：如同整理书架，让杂乱无章的数据项按照特定规则（如字母顺序、数字大小、日期先后）排列整齐。
2. ​重命名键 (Rename Keys)​：好比给文件批量重命名，将数据信息中含义相同但名称各异的“标签”（键 Key）统一成规范、清晰的格式。
3. ​执行数据 (Execution Data)​：像是给每次重要的会议做记录，为工作流的每一次运行（Execution）打上特殊的“标记”，方便后续追踪、筛选和审计。
4. ​比较数据集 (Compare Datasets)​：如同财务对账，快速找出两份数据列表（例如，本月和上月的客户名单）之间的相同项、差异项、新增项和移除项。
5. ​加密 (Crypto)​：提供基础的数据安全工具，比如为数据生成“指纹”（哈希）以校验完整性，或生成唯一的身份标识符。

准备好了吗？现在，就让翔宇带领你，一同踏入 n8n 的数据魔法世界，解锁自动化数据处理的强大能力吧！

第一章：排序 (Sort)

节点概览：让数据井然有序

在日常工作中，我们经常会遇到需要整理数据顺序的情况。想象一下，你从数据库或者电子表格中导出了一份长长的客户名单、产品列表或者订单记录，但它们的顺序是混乱的，查找特定信息或者进行后续分析都非常不便。这时，n8n 中的排序 (Sort) 节点就能派上大用场了。

排序 (Sort) 节点是 n8n 提供的一个核心数据处理工具 ，它的核心功能就是接收一系列输入的数据项 (Items)，然后根据你设定的规则，对这些数据项进行重新排列。你可以指定按照哪个或哪些字段（比如客户姓名、产品价格、订单创建日期等）进行排序，并决定是升序（从小到大、从早到晚）还是降序（从大到小、从晚到早）。此外，它还提供了一个特殊的功能，可以将数据项的顺序完全随机打乱，这在需要随机抽样或进行抽奖等场景下非常有用 。

简而言之，排序 (Sort) 节点就是你工作流中的数据整理专家，帮助你将无序的数据流转化为结构清晰、易于处理的有序序列。

参数配置：排序

配置排序 (Sort) 节点非常直观，大部分常见的排序需求都可以通过图形界面轻松完成，无需编写代码。节点的核心配置在于 类型 (Type) 参数，它决定了你要使用哪种排序方式 。

• ​类型 (Type)​:
  • ​简单 (Simple)​: 这是最常用也是最基础的排序模式，适用于根据一个或多个字段进行升序或降序排列。
    • ​添加排序字段​: 点击 Add Field To Sort By 按钮，会看到两个主要的配置项：
      • Field Name: 在这里输入你希望依据其值进行排序的字段名称（键 Key）。例如，如果你想根据客户的注册时间排序，并且该信息存储在名为 registrationDate 的字段中，那么你就在这里填入 registrationDate。
      • Order: 选择排序的方向。Ascending 表示升序（例如，数字从小到大，日期从早到晚，字母从 A 到 Z），Descending 表示降序（例如，数字从大到小，日期从晚到早，字母从 Z 到 A） 。
    • ​多级排序​: 你可以多次点击 Add Field To Sort By 添加多个排序规则。n8n 会按照你添加的顺序进行多级排序。例如，你可以先设置按 城市 (city) 字段升序排序，然后再添加一个规则按 销售额 (salesAmount) 字段降序排序。这样，结果会首先按城市分组，在同一个城市内部，再按销售额从高到低排列。
    • ​简单选项 (Simple options)​: 在 Simple 模式下，还有一个额外的选项 Disable Dot Notation 。默认情况下，n8n 允许你使用点 . 来访问嵌套对象中的字段，比如 customer.address.zipCode。这种表示法称为“点表示法 (Dot Notation)”。但如果你的字段名本身就包含了点 .（例如，字段名是 version.number 而不是一个名为 version 的对象里包含 number 字段），并且你希望 n8n 将其视为一个整体的字段名，而不是试图进行嵌套访问，那么你可以勾选 Disable Dot Notation。不过，对于大多数初学者而言，保持默认设置（不勾选）通常是合适的。
  • ​随机 (Random)​: 这个模式非常直接，它会接收所有输入的数据项，然后将它们的顺序完全随机地打乱。选择此模式后，无需再配置任何排序字段或顺序 。这对于需要公平抽样或者进行随机分配任务的场景非常有用。
  • ​代码 (Code)​: 这个模式提供了最大的灵活性，允许你通过编写 JavaScript 代码来自定义排序逻辑 。你可以实现非常复杂的比较规则，比如根据特定条件赋予不同项不同的权重再排序，或者处理非标准的数据格式。
    • ​翔宇特别提醒​: 对于零代码基础的用户，翔宇强烈建议现阶段完全忽略这个 Code 模式。它需要扎实的 JavaScript 编程知识，包括理解 n8n 的数据结构和执行环境。贸然使用不仅难以成功，还可能引入难以排查的错误。我们的目标是利用 n8n 的可视化能力解决问题，Simple 和 Random 模式已经能满足绝大多数常见需求。当你对 n8n 和数据处理有了更深入的理解后，再考虑探索 Code 模式也不迟。
• ​排序行为的底层机制​: 了解 Simple 模式排序的工作原理对于避免一些常见误区非常有帮助。n8n 的排序功能，特别是 Simple 模式，底层依赖的是 JavaScript 语言内置的数组排序 (Array.sort) 行为 。这个默认行为有一个特点：在比较两个元素之前，它通常会先将这两个元素​转换成字符串​，然后再按照字符串的字典顺序进行比较。
  • 这意味着什么呢？举个例子，如果你有一组数字 ，并希望按升序排列。你可能会期望得到。但如果按照默认的字符串比较，”10″ 这个字符串会排在 “2” 这个字符串之前（因为字符 ‘1’ 比字符 ‘2’ 小），可能会导致排序结果是 或者（取决于具体实现，但不是纯数值意义上的 “）。
  • 这个特性对于纯文本排序通常没有问题，但对于需要精确按数值大小排序的场景，就可能产生非预期的结果。虽然 n8n 可能在某些情况下做了优化尝试进行数值比较，但理解这个底层机制有助于解释一些看似奇怪的排序现象。如果遇到严格的数值排序问题，最可靠的解决方案通常还是依赖 Code 模式进行显式的数值比较，但这超出了本教程的范围。

数据映射与表达式：告诉 n8n 如何排序

在配置排序 (Sort) 节点的 Simple 模式时，最关键的一步是正确指定 Field Name，也就是告知 n8n 你要根据哪个字段的值来进行排序。

• ​字段名的来源​: 这个 Field Name 必须是存在于输入到排序节点的数据项 (Item)中的 json 对象里的​键 (Key)​。你需要确保你填写的名称与数据中实际的键名完全一致，包括大小写。
  • 例如，假设上一个节点传递给排序节点的数据结构如下（这里用简化方式展示两个 Item）：[ { "json": { "productName": "Laptop", "price": 1200, "stock": 15 } }, { "json": { "productName": "Mouse", "price": 25, "stock": 150 } } ] ​
  • 如果你想按照价格 (price) 升序排序，那么在 Field Name 中就应该填入 price。
  • 如果你想按照产品名称 (productName) 字母顺序排序，就填入 productName。
  • 如果你想按照库存 (stock) 降序排序，就填入 stock 并选择 Descending。
• ​使用表达式 (Expressions)​: 虽然对于简单的排序，直接填写字段名是最常见的方式，但 n8n 的 Field Name 输入框也支持使用表达式 {{ }} 。表达式允许你动态地生成字段名，或者对字段值进行预处理后再排序（但这通常是在 Code 模式下完成比较逻辑，而不是在 Field Name 里做复杂转换）。
  • ​翔宇建议​: 对于初学者，在 Simple 模式下，尽量避免在 Field Name 中使用复杂的表达式。直接使用准确的字段名更清晰、更不易出错。表达式的强大之处在于动态配置，但在排序字段这个场景下，除非你有非常特殊的需求（比如排序依据的字段名本身是动态变化的），否则直接指定字段名是最佳实践。过度使用表达式会不必要地增加工作流的复杂度和调试难度。
• ​检查输入数据​: 如果不确定确切的字段名，或者想确认数据结构，可以在 n8n 编辑器中点击排序节点上方的输入数据区域（通常显示为上一个节点的图标和名称），n8n 会展示流入该节点的数据样本。你可以检查 json 对象中有哪些可用的键，以及它们的准确名称。这是避免因字段名错误导致排序失败或无效的最佳方法。

应用场景：

排序 (Sort) 节点虽然功能单一，但在实际的自动化工作流中应用极为广泛。以下是翔宇在实践中常用到排序节点的一些场景：

1. ​整理客户/订单列表​:
   • ​场景​: 从 CRM 系统、数据库或 Google Sheets 等来源获取了大量客户或订单数据。
   • ​应用​: 使用排序节点，可以轻松地按照客户的注册日期 (registrationDate) 升序排列，找出最早的一批用户；或者按照订单金额 (orderAmount) 降序排列，快速定位高价值订单；或者按最后联系时间 (lastContactDate) 降序排列，优先处理近期互动的客户。排序后的数据便于生成报告、进行客户分层或执行后续的营销活动。
2. ​内容推荐与展示​:
   • ​场景​: 搭建了一个内容聚合或发布的自动化流程，从 RSS Feed、API 或数据库获取了文章、博客帖子或新闻列表。
   • ​应用​: 使用排序节点按发布时间 (publishDate) 降序排序，确保在网站、邮件通讯或社交媒体上总是优先展示最新的内容。也可以按阅读量 (viewCount) 或点赞数 (likeCount) 降序排序，推荐热门内容。
3. ​生成排行榜​:
   • ​场景​: 自动化处理来自游戏、销售系统或在线课程平台的数据。
   • ​应用​: 根据玩家得分 (score)、销售业绩 (salesPerformance) 或课程完成度 (completionRate) 进行降序排序，然后可能结合 Limit 节点 选取前 10 名或前 50 名，轻松生成各种排行榜，用于展示、激励或分析。
4. ​执行抽奖活动​:
   • ​场景​: 举办线上活动，收集了一份参与用户的名单。
   • ​应用​: 先将用户列表（例如，从表单提交、数据库查询得到）输入到排序节点，选择 Random 模式进行完全随机排序。然后，连接一个 Limit 节点，设置需要抽取的获奖人数（例如，取随机排序后的前 3 名）。这样就实现了一个公平、透明的自动化抽奖过程。
5. ​任务优先级管理​:
   • ​场景​: 通过 n8n 连接到项目管理工具（如 Asana , Trello, Jira 等），获取了待办任务列表。
   • ​应用​: 使用排序节点，首先按任务的优先级 (priority) 字段降序排序（假设高优先级值更大），然后对于相同优先级的任务，再按截止日期 (dueDate) 升序排序。这样处理后的任务列表，排在最前面的就是最高优先级且最紧急的任务，便于自动化地分配、提醒或执行。
6. ​数据比对前的预处理​:
   • ​场景​: 在使用 Compare Datasets 节点（我们将在后续章节介绍）比较两个数据集之前，有时需要确保两个数据集内部的顺序是一致的，或者至少是可预测的。
   • ​应用​: 分别对两个输入数据集使用排序节点，按照相同的匹配键（例如 userID）进行排序。虽然 Compare Datasets 节点本身不要求输入有序，但在某些复杂逻辑或调试过程中，预先排序可以使数据流更清晰。

这些只是排序节点众多应用中的冰山一角。它的核心价值在于为后续的数据处理步骤提供一个有序、结构化的基础，从而简化逻辑、提高效率。

常见报错及解决方案：排序不符合预期怎么办？

在使用排序 (Sort) 节点时，虽然配置简单，但有时也可能遇到排序结果不符合预期或节点报错的情况。以下是一些常见问题及其分析和解决方案：

• ​问题​: 排序结果看起来不对，特别是涉及到数字时。
  • ​翔宇分析​: 正如前面提到的，这很可能是因为 Simple 模式默认按照字符串进行比较 。例如，数字 100 会排在 20 之前，因为字符串 “100” 的第一个字符 ‘1’ 在字母表中小于字符串 “20” 的第一个字符 ‘2’。同样，日期如果存储为 “MM/DD/YYYY” 格式的字符串，直接按字符串排序可能不会得到正确的 chronological 顺序。
  • ​解决方案​:
    1. ​检查数据类型​: 确保你尝试排序的字段确实是数值类型或可直接比较的日期类型。如果数据源是可控的（如数据库查询），尽量在源头保证数据类型正确。
    2. ​数据格式规范化​: 如果是数值排序，可以尝试将数字格式化为固定长度（例如，不足位数的在前面补零，如 002, 010, 100），这样字符串排序也能得到正确结果，但这治标不治本且不通用。对于日期，使用 ISO 8601 格式 (YYYY-MM-DDTHH:mm:ssZ) 的字符串通常能保证正确的字典序排序。
    3. ​源头排序​: 如果可能，在获取数据的步骤（如数据库查询节点、HTTP Request 节点的参数）就进行排序，避免在 n8n 中处理复杂的排序逻辑。
    4. ​高级方案 (Code 节点)​: 对于严格且复杂的排序需求（特别是混合类型或需要自定义逻辑的数值排序），最终的解决方案往往是使用 Code 节点编写 JavaScript 代码，进行显式的数值转换和比较。但这需要编程知识。
• ​问题​: 节点报错，提示类似 “Cannot read property ‘xxx’ of undefined” 或找不到指定的排序字段。
  • ​翔宇分析​: 这通常意味着你在 Field Name 中指定的字段名，在流入排序节点的某些（或所有）数据项 (Item) 的 json 对象中并不存在，或者存在拼写错误、大小写不匹配的问题 。也可能是数据流中某个环节出了问题，导致流入的数据结构不完整。
  • ​解决方案​:
    1. ​核对字段名​: 仔细检查你在 Field Name 中输入的名称。回到上一个节点的输出视图，确认该字段确实存在于 json 对象中，并且名称、大小写完全一致。
    2. ​检查数据流​: 确保上游节点成功执行，并且输出了包含所需字段的有效数据。可能需要检查更早的节点是否有错误或逻辑问题。
    3. ​处理缺失值​: 如果某些数据项可能缺少排序字段，你需要考虑如何处理。一种方法是在排序前使用 IF 节点或 Filter 节点将这些项分离出去，或者使用 Set 节点给它们赋一个默认值。
• ​问题​: 使用了嵌套字段（例如 customer.address.city）进行排序，但排序没有生效或结果错误。
  • ​翔宇分析​:
    1. ​路径错误​: 嵌套路径的写法可能不正确，比如层级名写错，或者某个中间层级不存在。
    2. ​Dot Notation 设置​: 可能不小心在 Simple options 中勾选了 Disable Dot Notation，导致 n8n 没有按预期解析嵌套路径 。
    3. ​数据不一致​: 某些数据项中可能缺少完整的嵌套结构。
  • ​解决方案​:
    1. ​验证路径​: 在上游节点的输出视图中，仔细检查嵌套结构和每一级的确切名称。
    2. ​检查选项​: 确保 Disable Dot Notation 没有被错误地勾选。
    3. ​数据一致性​: 考虑如何处理数据结构不一致的情况，可能需要预处理数据。
• ​问题​: 排序包含特殊字符（如中文、符号）的字段时，结果不符合直觉。
  • ​翔宇分析​: 排序行为依赖于底层 JavaScript 环境的区域设置 (locale) 和字符编码。不同环境下的排序规则可能略有差异，特别是对于非 ASCII 字符。
  • ​解决方案​: 大多数情况下，对于 UTF-8 编码的中文字符串，默认排序能按拼音或 Unicode 顺序工作。如果需要特定的排序规则（如按笔画），则几乎肯定需要使用 Code 节点实现自定义逻辑。对于特殊符号，其排序位置取决于它们在 Unicode 编码表中的顺序。

注意事项：排序中的小陷阱

在使用排序 (Sort) 节点时，除了上述常见问题，还有一些细节需要留意，以确保工作流的稳定和准确：

• ​数据类型是关键​: 再次强调，务必关注你要排序的字段的数据类型。Simple 模式默认按字符串比较的行为是许多“意外”排序结果的根源，尤其对于数字和日期 。
• ​大小写敏感性​: 默认情况下，字符串排序是区分大小写的。例如，”Apple” 会排在 “banana” 之前。如果需要不区分大小写的排序，你可能需要在排序前使用 Set 节点或 Code 节点将所有待排序的字符串统一转换为大写或小写。
• ​空值 (null) 和缺失字段​: 如果数据项中排序字段的值是 null，或者根本不存在该字段，它们在排序结果中的位置可能因 n8n 版本或底层实现而异。通常，它们会被排在所有有效值的前面或后面。在设计工作流时，要考虑到这种情况，并决定是否需要预先处理这些特殊项。
• ​性能考量​: 对非常大的数据集（例如，包含数十万甚至数百万个 Item）进行排序，可能会消耗大量的计算时间和内存资源。如果在资源受限的环境（如基础版的 n8n Cloud 或配置较低的自托管服务器）中运行，这可能导致工作流执行缓慢甚至失败。在这种情况下，应优先考虑在数据源头（如数据库层面使用 ORDER BY 子句）完成排序，或者优化工作流逻辑，减少需要排序的数据量。
• ​稳定性​: 排序操作通常是稳定的，这意味着如果两个数据项根据排序规则被认为相等，它们在排序后的相对顺序将保持与排序前一致。这在多级排序或处理重复值时比较重要。
• ​Random 模式的随机性​: Random 模式使用的是伪随机数生成器。对于大多数应用场景（如抽奖）来说足够随机，但如果需要密码学安全级别的随机性，则不应依赖此模式。

理解并注意这些细节，可以帮助你更有效地使用排序 (Sort) 节点，避免常见问题，并构建出更健壮、更符合预期的自动化流程。

第二章：重命名键 (Rename Keys)

节点概览：给数据换个“名字”

在构建自动化工作流时，你经常需要整合来自不同系统、API 或文件的数据。一个常见的问题是，这些不同的数据源对于同一个概念可能使用不同的字段名称（即 JSON 数据中的“键” Key）。例如，客户的电子邮件地址在一个系统中可能被称为 email_address，在另一个系统中是 userEmail，而在第三个系统中可能直接就是 email。这种不一致性会给后续的数据处理、合并或存储带来极大的麻烦，因为你需要编写复杂的逻辑来处理这些不同的名称。

这时，重命名键 (Rename Keys) 节点就如同你的数据“规范化”助手闪亮登场了。它的核心功能非常明确：接收输入的数据项 (Items)，并根据你设定的规则，修改这些数据项 json 对象中的键 (Key) 的名称 。你可以将 email_address 和 userEmail 都统一修改为标准的 email，从而让后续的处理节点（如写入数据库、更新 CRM）能够使用一致的字段名进行操作。

重命名键 (Rename Keys) 节点是 n8n 提供的一个基础且强大的核心数据转换工具 ，它帮助你清理和统一数据结构，是实现数据整合与标准化的重要一环。

参数配置：精确定位与批量修改

配置重命名键 (Rename Keys) 节点的核心在于建立一个清晰的“旧键名”到“新键名”的映射关系，或者定义一个批量修改键名的规则 。

• ​单个键重命名 (Mapping Mode)​: 这是最常用、最直观的方式，适用于精确地修改一个或多个特定的键名。
  • 点击界面上的 Add new key 按钮，每点击一次就会添加一条重命名规则 。
  • 对于每一条规则，你需要配置两个核心参数：
    • Current Key Name: 在这里输入你想要修改的当前键的名称。这个名称必须与输入数据项 json 对象中实际存在的键名完全匹配（包括大小写） 。
    • New Key Name: 在这里输入你希望将该键修改为的新名称。你可以使用任何你认为合适的、合法的键名 。
  • 你可以添加任意多条这样的规则，n8n 会在处理每个数据项时，应用所有这些规则，一次性完成多个键的重命名。例如，你可以同时添加规则将 fname 改为 firstName，将 lname 改为 lastName。
• ​使用正则表达式 (Use Regex)​: 这是一种更高级、更强大的批量重命名方式，允许你使用一个正则表达式模式来查找并替换符合该模式的所有键名 。
  • ​翔宇解读 (Regex)​: 正则表达式 (Regular Expression, Regex) 是一种用于描述、匹配一系列符合某个句法规则的字符串的强大工具。你可以把它想象成一种高级的“查找与替换”语言。例如，你可以用一个简单的 Regex 规则 ^_ 来匹配所有以下划线开头的键名，然后将其替换为空字符串，从而批量删除键名的前缀下划线。
  • 要启用此模式，首先需要勾选节点参数中的 Use Regex 复选框。之后，会出现以下配置项：
    • Regular Expression: 在这里输入你的正则表达式模式 。例如，要匹配所有以 data_ 开头的键，可以输入 ^data_。
    • Replace With: 输入用于替换匹配部分的文本 。你可以使用特殊的占位符（如 $1, $2）来引用正则表达式中用括号 () 捕获的分组。例如，如果 Regex 是 ^(user)_(id)$，Replace With 设为 $1Id，则会将 user_id 重命名为 userId。如果只想删除匹配的部分，可以将此项留空或根据 Regex 写法调整。
    • ​Regex 选项​:
      • Case Insensitive: 勾选此项表示在匹配键名时忽略大小写差异 。
      • Max Depth: 这个参数控制 Regex 查找和替换操作在嵌套数据结构中进行的最大深度 。0 表示只处理顶层的键；-1 (默认值) 表示深入到所有层级进行查找和替换；正整数 n 表示最多深入到 n 层。例如，如果设为 1，它会处理顶层键和第一层嵌套对象内的键，但不会处理更深层级的键。
  • ​翔宇特别警告 (Regex 的复杂性与风险)​:
    1. ​学习曲线​: 正则表达式本身是一门独立的、有一定复杂度的技术。对于完全没有接触过 Regex 的新手来说，直接上手可能会非常困难且容易出错。翔宇建议，除非你确实需要进行复杂的、模式化的批量重命名，否则优先考虑使用更简单、更明确的单个键重命名方式。
    2. ​潜在影响​: 使用 Regex 进行重命名时必须格外小心！一个不够精确的 Regex 模式可能会匹配到你意料之外的键名，导致数据结构被意外破坏。更需要注意的是，Regex 操作可能会影响到你之前通过“单个键重命名”规则已经修改过的键 。例如，你先将 old_name 改为 newName，然后使用一个 Regex 规则将所有包含 Name 的键改为 Identifier，那么你最初得到的 newName 也会被再次修改为 newIdentifier。因此，在使用 Regex 模式时，务必进行充分的测试，确保其影响范围符合你的预期。如果规则复杂，最好在一个隔离的测试工作流中反复验证。

数据映射与表达式：找到你要改的“键”

配置重命名键 (Rename Keys) 节点时，理解它如何与输入数据进行交互非常重要。

• ​定位当前键 (Current Key Name)​:
  • 在“单个键重命名”模式下，Current Key Name 必须精确匹配输入数据项 (Item) 的 json 对象中实际存在的键名。大小写、空格等都必须一致。
  • 在“使用正则表达式”模式下，Regular Expression 定义了匹配键名的模式。
  • ​不支持表达式​: 需要注意的是，Current Key Name 和 Regular Expression 这两个参数本身通常不支持使用 n8n 的表达式 {{ }}。你不能动态地生成要查找的旧键名或 Regex 模式。你需要直接输入静态的文本。
• ​定义新键 (New Key Name / Replace With)​:
  • New Key Name (在单个模式下) 和 Replace With (在 Regex 模式下) 定义了重命名后的键名。这些新键名应该是你期望的、符合规范的名称。它们同样通常不支持直接使用表达式来动态生成。
• ​核心限制：难以处理嵌套数组内的键​: 这是使用重命名键 (Rename Keys) 节点时一个非常关键且常见的限制点，许多用户在此遇到困难 。这个节点主要设计用于处理数据项 json 对象顶层的键，或者嵌套对象 (Object)内部的键（如果 Max Depth 设置允许）。但是，如果你想重命名一个数组 (Array)内部每一个对象共有的某个键，这个节点通常​无法直接完成​。
  • ​翔宇举例说明​: 假设你的输入数据是这样的：{ "orderId": 123, "items": } ​你想将数组 items 内部每个对象的 product_sku 重命名为 sku，将 quantity_ordered 重命名为 quantity。直接使用重命名键 (Rename Keys) 节点，配置 Current Key Name 为 product_sku 或 quantity_ordered 是行不通的，因为它无法自动遍历数组并对内部对象进行操作。
  • ​解决方案​: 对于这种需要深入数组内部进行批量键重命名的复杂场景，标准的解决方案是使用 Code 节点 。在 Code 节点中，你可以用 JavaScript 代码遍历数组，并对每个元素对象执行键的重命名操作。这再次凸显了 Code 节点在处理复杂数据结构时的灵活性，但也意味着超出了纯粹的无代码范畴。
• ​特殊字符的处理​: 键名中是否可以包含特殊字符，比如冒号 :、空格、或者中文？根据 n8n 社区的讨论和实践经验 ，重命名键节点通常能够处理包含这些特殊字符的键名，只要你在 Current Key Name 中输入的是完全准确的、原始的键名即可。例如，如果原始键名是 content:encodedSnippet，你可以直接在 Current Key Name 中输入它，然后在 New Key Name 中指定一个不含特殊字符的新名称（如 encodedSnippet）。关键在于精确匹配原始键名。

应用场景：统一接口数据，告别混乱

重命名键 (Rename Keys) 节点在各种需要数据整合、清洗和标准化的场景中都扮演着重要角色。以下是一些翔宇经常遇到的应用实例：

1. ​整合多渠道销售/营销数据​:
   • ​场景​: 你可能同时在多个电商平台（如 Shopify , WooCommerce, Amazon）销售产品，或者使用不同的营销工具（如不同的 CRM、邮件服务商）。这些平台和工具返回的数据，字段命名规则往往各不相同。
   • ​应用​: 在将这些数据汇总到你的中心数据库或数据仓库之前，使用重命名键节点进行预处理。例如，将来自不同来源的表示客户邮箱的字段（可能是 customer_email, buyerEmail, client_mail, contact-email 等）统一重命名为标准的 email。同样，可以统一地址、电话、订单 ID 等字段的命名，确保后续分析和报告的准确性。
2. ​处理第三方 API 响应​:
   • ​场景​: 你使用 n8n 的 HTTP Request 节点 调用了一个外部 API。该 API 返回的 JSON 数据中，键名可能包含特殊字符（如 @, :, .），或者使用了你不喜欢的命名风格（如全大写、下划线过多），或者层级嵌套过深。
   • ​应用​: 在接收到 API 响应后，紧接着使用重命名键节点进行清理。将包含特殊字符的键改为合规的名称，将不符合内部规范的键名调整过来（例如，USER_ID 改为 userId），甚至可以将深层嵌套的键（如 response.data.user.profile.primary_email）直接重命名为一个更易于访问的顶层键 email（注意：这只改变键名，不改变值的层级关系，如果想提取值到顶层需要用 Set 节点）。
3. ​数据导入前的准备​:
   • ​场景​: 你需要将从 Excel 文件 、CSV 文件或 Google Sheets 中读取的数据导入到数据库、CRM 或其他系统中。这些源文件中的列名（会被 n8n 解析为 JSON 的键）可能包含空格、中文、特殊符号，或者不符合目标系统的字段命名要求。
   • ​应用​: 在读取文件数据后，使用重命名键节点，将这些列名（键）批量修改为目标系统可以接受的格式，例如，将 “客户 名称” 改为 customer_name，将 “订单总额(含税)” 改为 order_total_tax_included。
4. ​简化和标准化内部数据流​:
   • ​场景​: 在一个复杂的工作流中，数据可能经过多个节点的处理和转换，导致中间步骤产生了一些临时性或不规范的键名。
   • ​应用​: 在关键的数据交接点，或者在最终输出数据之前，使用重命名键节点进行一次“整理”，确保流转到下游节点或最终输出的数据结构清晰、命名统一，提高工作流的可读性和可维护性。

通过有效地使用重命名键节点，你可以大大降低处理异构数据源的复杂性，使得后续的数据操作更加流畅和可靠。

常见报错及解决方案：“键”找不到或改错？

尽管重命名键 (Rename Keys) 节点相对简单，但在使用过程中也可能遇到一些问题。以下是常见的状况及排查思路：

• ​问题​: 节点成功执行了，但是预期的某个键并没有被重命名。
  • ​翔宇分析​:
    1. ​Current Key Name 不匹配​: 这是最常见的原因。你输入的当前键名与实际数据中的键名在拼写、大小写或包含的空格等方面存在差异。人眼可能难以发现细微差别。
    2. ​键在嵌套数组内​: 如前所述，该节点无法直接重命名数组内部对象的键 。如果你尝试重命名的键位于数组结构深处，操作会失败。
    3. ​键不存在​: 输入的数据项中根本就不包含你指定的 Current Key Name。
  • ​解决方案​:
    1. ​精确核对​: 打开上一个节点的输出视图，仔细复制实际的键名，然后粘贴到 Current Key Name 输入框中，避免手动输入错误。
    2. ​确认数据结构​: 检查键是否位于嵌套数组内。如果是，你需要改用 Code 节点或其他方法。
    3. ​验证输入​: 确保上游节点确实输出了包含该键的数据项。
• ​问题​: 使用了正则表达式 (Regex) 模式后，一些不应该被修改的键也被重命名了，或者重命名的结果不是预期的。
  • ​翔宇分析​:
    1. ​Regex 过于宽泛​: 你编写的正则表达式模式匹配范围太广，意外地包含了其他键名 。
    2. ​替换逻辑错误​: Replace With 部分的逻辑（可能包含捕获组引用 $1 等）不正确，导致生成的新键名有误。
    3. ​Regex 引擎差异​: 不同环境下的 Regex 引擎可能存在细微的行为差异（虽然在 n8n 内部通常是一致的）。
  • ​解决方案​:
    1. ​收紧 Regex​: 修改正则表达式，使其更精确地只匹配你想要修改的目标键名。使用在线 Regex 测试工具（如 regex101.com）反复调试你的模式和替换逻辑，使用实际的键名样本进行测试。
    2. ​分步处理​: 如果一个 Regex 难以同时处理多种情况，可以考虑使用多个重命名键节点，或者结合其他节点（如 IF、Switch）分情况处理。
    3. ​简化​: 如果 Regex 过于复杂难以驾驭，回归到“单个键重命名”模式可能更可靠。
• ​问题​: 节点本身运行出错，抛出异常（虽然这种情况相对少见）。
  • ​翔宇分析​: 可能是遇到了 n8n 的内部 Bug，或者与特定的 n8n 版本有关。也可能是输入的数据结构极其异常，导致节点无法处理。
  • ​解决方案​:
    1. ​更新 n8n​: 尝试将 n8n 更新到最新的稳定版本，看看问题是否解决。
    2. ​简化测试​: 尝试在一个最简单的工作流中（例如，手动触发 -> Set 节点生成包含问题的键 -> Rename Keys）复现问题。
    3. ​社区求助​: 如果问题持续存在且无法自行解决，可以前往 n8n 官方社区 搜索是否有类似问题，或者发帖求助。提问时，务必提供你的 n8n 版本、运行环境、工作流示例（去除敏感信息）以及输入数据的样本，以便他人帮助诊断。
• ​问题​: 尝试重命名包含特殊字符（如 :）的键时失败。
  • ​翔宇分析​: 虽然通常可行 ，但失败可能是因为复制粘贴时引入了不可见字符，或者对特殊字符的处理在特定 n8n 版本或环境下存在问题。
  • ​解决方案​: 确保 Current Key Name 输入完全准确无误。再次尝试仔细复制粘贴。如果仍然失败，可以考虑在社区寻求帮助或查找是否有相关的已知问题。

通过理解这些常见问题及其原因，你可以更快地定位和解决在使用重命名键节点时遇到的障碍。

注意事项：

在使用重命名键 (Rename Keys) 节点时，特别是涉及到正则表达式 (Regex) 模式时，务必牢记以下几点，以确保操作的准确性和安全性：

• ​Regex 的复杂性​: 对于初学者而言，正则表达式的学习曲线陡峭，语法规则繁多，很容易写出错漏百出的模式。在没有充分理解和测试之前，贸然在生产环境中使用复杂的 Regex 进行键重命名是高风险操作。优先选择简单明了的“单个键重命名”方式。
• ​影响范围需谨慎评估​: 正则表达式的威力在于其模式匹配能力，但也正因如此，一个不够精确的模式可能会“误伤”大量非目标的键名，导致数据结构混乱 。在启用 Regex 前，务必仔细思考其可能匹配到的所有情况，并进行小范围、多场景的测试。
• ​嵌套数组的局限性​: 再次强调，无论是单个键重命名还是 Regex 模式，该节点都难以直接处理嵌套数组内部对象的键重命名 。这是该节点的一个核心设计限制，遇到此类需求时，应考虑使用 Code 节点。
• ​性能影响​: 虽然对于一般数据量，重命名键节点性能良好，但如果处理包含巨量数据项 (Items) 的输入，并且使用了复杂的正则表达式或者定义了大量的单个重命名规则，节点的处理时间可能会相应增加。在性能敏感的场景下需要考虑这一点。
• ​操作不可逆​: 键一旦被重命名，原始的键名信息就丢失了（除非你在后续步骤中再将其改回去）。确保你的重命名逻辑是正确的，并且符合下游节点的预期。
• ​调试难度​: 使用 Regex 模式时，如果出现问题，排查起来可能比单个键重命名模式更困难，因为你需要理解 Regex 的匹配逻辑。

总而言之，重命名键 (Rename Keys) 节点是一个强大的工具，但也需要谨慎使用。特别是对于 Regex 模式，务必充分理解其工作原理和潜在风险，做到“先测试，后应用”。

第三章：执行数据 (Execution Data)

节点概览：为工作流运行添加“标签”

当你开始构建和运行越来越多的 n8n 工作流时，管理和追踪它们的执行情况就变得尤为重要。n8n 会记录下每一次工作流的运行历史，我们称之为“执行” (Execution)。但有时，仅仅看到一长串的成功或失败记录是不够的，你可能希望能够更方便地对这些执行进行分类、筛选或添加一些上下文信息。

例如，假设你有一个处理客户订单的工作流，它每天都会运行很多次。你可能想区分哪些执行是处理来自“网站”的订单，哪些是来自“App”的订单；或者标记出哪些执行处理的是“加急”订单。

这时，执行数据 (Execution Data) 节点就派上用场了。它的核心功能非常专一：允许你在工作流运行的​过程中​，动态地设置一些自定义的元数据（以键值对 Key-Value Pair 的形式），这些元数据会与当前这次执行记录永久关联并存储起来 。你可以把这个过程想象成，给正在处理的这份文件（本次执行）贴上几个有意义的“标签”或“便签”。

这些你设置的自定义数据，最直接的用途是在 n8n 的“执行列表” (Executions list) 界面。你可以将这些自定义的键作为列来显示，并使用它们的值来过滤执行记录 。这样，你就能快速地找到所有处理“加急”订单的执行，或者所有来自“网站”渠道的执行，极大地方便了监控、调试和审计工作。

执行数据 (Execution Data) 节点是 n8n 提供的一个用于增强执行可管理性的核心工具 ，它专注于为单次执行附加描述性信息。

参数配置：轻松设置追踪信息

配置执行数据 (Execution Data) 节点非常简单明了，它的界面主要就是用来添加你想设置的键值对信息。

• ​添加字段 (Add Field)​: 点击 Add Field 按钮，即可添加一条你要设置的自定义数据。你可以多次点击，添加多条数据 。
• ​配置键值对​: 每一条自定义数据都需要配置两个参数：
  • Key: 输入你自定义的“标签”名称（也就是键）。这个名称应该具有描述性，方便你理解其含义。例如，你可以用 customerType, processingStatus, invoiceId 等作为 Key 。
    • ​限制​: Key 的名称有长度限制，最长不能超过50 个字符。
  • Value: 输入这个“标签”的具体值。这个值必须是字符串 (String)类型 。例如，对于 Key customerType，Value 可以是 "VIP" 或 "Regular"；对于 Key processingStatus，Value 可以是 "Pending" 或 "Completed"。
    • ​限制​: Value 作为字符串，其长度最长不能超过255 个字符。
• ​数量限制​: 一个工作流在一次执行中，最多只能设置10 个不同的自定义执行数据项 (Key-Value Pairs) 。如果你尝试设置超过 10 个，可能会出错或只有前 10 个生效。
• ​核心要点：只能设置，不能读取 (Set Only, No Get)​: 翔宇在这里必须重点强调一个非常关键的概念：执行数据 (Execution Data) 这个节点本身，其功能仅仅是设置 (Set)自定义数据。它就像一个只能往执行记录里“写入”标签的工具。你不能使用这个节点来读取 (Get)你在同一次执行中早些时候设置的数据，更不能读取其他执行记录设置的数据。
  • 如果你需要在工作流的后续步骤中访问或使用这些你设置的自定义执行数据（例如，根据之前设置的 customerType 来决定不同的处理路径），你需要使用 Code 节点，并通过 n8n 提供的特殊内置变量 $execution.customData (对于 JavaScript) 或 _execution.customData (对于 Python) 来实现 。$execution.customData 对象提供了 .get("key") 方法来读取单个值，以及 .getAll() 方法来获取所有已设置的自定义数据 。
  • 理解这个“只写不读”的特性对于正确使用 Execution Data 节点至关重要，避免产生误解，认为它可以像变量一样在节点间传递信息。
• ​功能可用性：可能依赖 n8n 版本和计划 (Plan Dependency)​: 另一个需要注意的重要事项是，设置和查看自定义执行数据这个功能，可能并非在所有 n8n 环境中都可用。根据 n8n 的官方文档 ，截至编写时（基于 v0.222.0 及以上版本信息），该功能明确支持以下环境：
  • ​n8n Cloud​: Pro 计划 和 Enterprise 计划。
  • ​n8n Self-Hosted (自托管)​: Enterprise 版本 和 已注册的 Community 版本。
  • 这意味着，如果你使用的是 n8n Cloud 的免费或 Starter 计划，或者未注册的自托管 Community 版本，你可能无法使用 Execution Data 节点来设置数据，或者即使设置了也无法在执行列表中看到或筛选它们。在使用此节点前，请务必确认你当前的 n8n 环境和版本是否支持此特性。

数据映射与表达式：静态与动态“标签”

在配置 Execution Data 节点的键值对时，你可以选择使用静态值或动态值。

• ​键 (Key)​: Key 参数通常建议使用​静态的、固定的字符串​。这样可以确保标签名称的一致性，方便在执行列表中进行筛选和识别。例如，始终使用 orderSource 作为表示订单来源的 Key。动态生成 Key 的情况非常罕见，也通常不推荐。
• ​值 (Value)​: Value 参数则更加灵活，它既可以是静态的，也可以是动态的。
  • ​静态 Value​: 你可以直接在 Value 输入框中输入一个固定的字符串。例如，在一个处理特定类型报告的工作流分支中，你可以设置一个固定的标签 reportType: "Monthly Summary"。所有走到这个节点的执行都会被打上这个相同的标签。
  • ​动态 Value (使用表达式)​: Value 输入框完全支持使用 n8n 的表达式 {{ }} 。这使得你可以根据工作流当前处理的数据，动态地生成标签的值。这是 Execution Data 节点最强大的用法之一。
    • ​示例​: 假设你的工作流由一个 Webhook 触发器启动，触发时会传入一个包含用户 ID (userId) 和订单金额 (amount) 的 JSON 数据。你可以这样设置动态标签：
      • ​规则 1​:
        • Key: triggerUserId
        • Value: {{ $trigger.item.json.userId }} (这里假设触发数据在 $trigger 节点的 item.json 中，且包含 userId 字段。你需要根据实际的触发器和数据结构调整表达式。)
      • ​规则 2​:
        • Key: orderValueCategory
        • Value: {{ $trigger.item.json.amount > 1000? "High Value" : "Regular Value" }} (这里使用了三元运算符表达式，根据订单金额动态判断并设置值为 “High Value” 或 “Regular Value”。)
  • ​翔宇提示 (动态 Value 注意事项)​:
    1. ​必须是字符串​: 无论你的表达式计算结果是什么类型（数字、布尔值等），最终传递给 Execution Data 的值必须是字符串。如果表达式结果不是字符串，n8n 可能会尝试自动转换，但也可能导致错误。最好在表达式中确保输出的是字符串格式。
    2. ​长度限制​: 动态生成的字符串长度同样不能超过255 个字符。如果表达式可能产生很长的结果，需要进行截断或处理。
    3. ​表达式有效性​: 确保你的表达式能够稳定地从上游节点获取到有效数据。如果表达式引用的数据不存在或为 null，可能会导致设置失败或设置了非预期的值（如空字符串）。

通过结合静态和动态 Value，你可以非常灵活地为每次工作流执行附加丰富且有意义的上下文信息。

应用场景：分类管理执行结果

Execution Data 节点的核心价值在于提升工作流执行的可观测性和可管理性。以下是翔宇在实践中常用此节点的一些具体场景：

1. ​区分处理类型或来源​:
   • ​场景​: 一个工作流可能处理多种类型的输入，或者由不同的源头触发。例如，一个通用的新用户注册流程，用户可能来自网站注册、App 注册或后台手动添加。
   • ​应用​: 在工作流的早期阶段，根据输入数据的某个特征（如 source 字段）或触发器的不同，使用 Execution Data 节点打上标签。例如，设置 registrationSource: "Website" 或 registrationSource: "App"。之后在查看执行列表时，就可以按 registrationSource 筛选，分别查看来自不同渠道的注册处理情况。
2. ​标记处理阶段或状态​:
   • ​场景​: 对于一个包含多个步骤、运行时间较长的复杂工作流，你可能想知道每次执行具体进行到了哪个阶段，或者最终是以哪种状态结束的。
   • ​应用​: 可以在工作流的关键节点之后放置 Execution Data 节点来更新一个状态标签。例如：
     • 流程开始时，设置 processingStage: "Started"。
     • 完成数据验证后，更新为 processingStage: "ValidationComplete"。
     • 调用外部 API 成功后，更新为 processingStage: "ApiCallSuccessful"。
     • 流程成功结束时，设置为 processingStage: "Finished"。
     • 如果在某个错误处理分支结束，设置为 processingStage: "Failed - Step X"。
     • ​注意​: 对同一个 Key 多次设置 Value，后面的会覆盖前面的。这正好适用于更新状态。通过查看执行列表中的 processingStage 列，可以快速了解每个执行的进展和最终结果。
3. ​记录关键业务标识符​:
   • ​场景​: 工作流处理的核心通常是围绕某个具体的业务实体，如订单 ID、用户 ID、文档编号、交易流水号等。当需要根据这些业务 ID 追踪某次具体的自动化处理过程时，仅靠 n8n 内部的执行 ID 可能不够直观。
   • ​应用​: 在获取到关键业务标识符后（例如，从触发器数据或数据库查询结果中），立即使用 Execution Data 节点将其设置为一个自定义字段。例如：
     • Key: orderId
     • Value: {{ $json.orderNumber }} (假设订单号在当前 Item 的 orderNumber 字段)
     • Key: processedDocumentId
     • Value: {{ $json.docId }}
   • 这样，当业务部门询问“订单号 XYZ123 的自动化处理情况如何？”时，你就可以直接在 n8n 执行列表中按 orderId 字段筛选 XYZ123，快速定位到相关的执行记录及其详细日志。
4. ​辅助调试和监控​:
   • ​场景​: 在开发和测试工作流时，或者在监控生产环境的工作流时，可能需要记录一些临时的调试信息或关键的性能指标。
   • ​应用​: 可以临时添加 Execution Data 节点来记录某些变量的值、某个步骤的处理耗时（需要配合 Code 节点计算时间差）或者分支判断的结果。例如，设置 debugInfo: "{{ $json.someVariable }}" 或 branchTaken: "Path A"。虽然这些信息也可以在节点输出中看到，但将最关键的指标或状态提升到执行数据层面，可以让你在不深入每个节点的情况下，通过执行列表快速概览关键信息。

通过创造性地使用 Execution Data 节点，你可以极大地提升对 n8n 工作流执行过程的洞察力，使得管理和维护自动化流程更加高效。

常见报错及解决方案：设置的数据去哪了？

虽然 Execution Data 节点配置简单，但在使用和查看其效果时，也可能遇到一些问题。

• ​问题​: 在 Execution Data 节点中设置了自定义数据，但在 n8n 的“执行列表” (Executions list) 页面看不到对应的列，或者无法按这些字段进行筛选。
  • ​翔宇分析​:
    1. ​功能可用性​: 最可能的原因是你的 n8n 版本或所使用的计划（Plan）不支持自定义执行数据功能 。请回顾前面提到的 Plan Dependency 部分，确认你的环境是否满足要求。
    2. ​界面操作​: 你可能需要在执行列表页面的设置中，手动选择将你设置的自定义 Key 添加为显示的列。同样，筛选功能也需要你主动添加基于这些 Key 的过滤条件。确认你熟悉执行列表界面的操作。
    3. ​节点未执行​: 工作流可能因为在 Execution Data 节点之前的某个步骤出错而提前终止，导致该节点根本没有被执行。
    4. ​n8n 配置问题​: 在极少数情况下，可能是 n8n 的数据库或配置存在问题，导致数据未能正确存储或读取（但这通常会伴随其他更明显的错误）。
  • ​解决方案​:
    1. ​检查环境​: 确认你的 n8n Cloud 计划或自托管版本支持此功能。
    2. ​配置列表视图​: 前往 Executions 页面，查找列配置或筛选器选项，尝试添加你设置的 Key。
    3. ​检查工作流状态​: 确认目标执行记录的状态是“成功”(Success)，并且执行流程图显示 Execution Data 节点已被执行（通常会高亮显示）。
    4. ​重启/检查日志​: 如果怀疑是 n8n 本身的问题，可以尝试重启 n8n 服务（如果是自托管），并检查 n8n 的后台日志是否有相关错误信息。
• ​问题​: Execution Data 节点执行时报错。
  • ​翔宇分析​:
    1. ​违反限制​: 你设置的 Key 超过了 50 字符，或者 Value 超过了 255 字符 。
    2. ​Value 类型错误​: 你试图设置一个非字符串类型的值，并且 n8n 未能自动转换或不允许转换 。
    3. ​数量超限​: 你在一个执行中尝试设置超过 10 个自定义字段 。
    4. ​表达式错误​: 如果 Value 使用了表达式，该表达式可能存在语法错误，或者引用的上游数据无效（如 null 或 undefined），导致无法生成有效的字符串值。
  • ​解决方案​:
    1. ​检查限制​: 仔细核对所有 Key 和 Value 的长度。
    2. ​确保字符串​: 确保传递给 Value 的是字符串。如果使用表达式，可以在表达式内部进行类型转换（例如，{{ $json.numberValue.toString() }}）。
    3. ​控制数量​: 检查是否设置了超过 10 个字段，如果是，需要精简。
    4. ​调试表达式​: 测试 Value 中使用的表达式，确保它能在各种情况下都返回有效的、符合长度限制的字符串。可以使用 Set 节点或 Code 节点先对表达式求值并检查结果。
• ​问题​: 在其他节点（如下游的 HTTP Request 或 Set 节点）遇到了 “No execution data available” 的错误，感觉可能与 Execution Data 节点有关。
  • ​翔宇分析​: 这个错误信息本身通常意味着下游节点在尝试访问其输入数据时遇到了问题，而不是直接与 Execution Data 节点设置的元数据有关 。然而，可能有间接联系：
    1. ​上游数据问题​: 如果 Execution Data 节点的 Value 表达式依赖的上游节点（比如一个数据库查询节点）没有正确执行或返回空数据，那么这个表达式可能失败。虽然 Execution Data 节点本身可能不报错（或报一个关于表达式的错），但下游节点可能因为缺少预期的输入数据而报错 “No execution data available”。
    2. ​工作流执行中断​: 在某些极端情况下，例如工作流因为内存耗尽而崩溃 ，可能导致整个执行记录不完整或损坏，从而在查看或后续处理时出现此错误。
    3. ​自定义节点问题 (罕见)​: 如社区帖子 中提到的，如果是使用​自定义开发的节点​，并且该节点错误地修改了传入的数据引用，可能会导致后续节点（包括查看执行数据时）出现混乱。但这不适用于使用 n8n 内置节点的情况。
  • ​解决方案​:
    1. ​检查上游​: 仔细检查 Execution Data 节点之前的所有节点是否都成功执行，并产生了预期的输出数据。
    2. ​检查表达式依赖​: 确认 Execution Data 节点中 Value 表达式所依赖的数据是否稳定可靠。
    3. ​资源监控​: 如果怀疑是资源问题（如内存不足），需要检查 n8n 的运行环境和资源使用情况。
    4. ​简化排查​: 尝试暂时禁用 Execution Data 节点，看下游的错误是否消失，以判断是否存在间接关联。

理解这些常见问题有助于你更顺利地利用 Execution Data 节点来增强工作流的可管理性。

注意事项：功能限制与适用范围

在使用 Execution Data 节点时，务必清楚其设计目的和局限性，避免误用：

• ​只写不读 (Set Only)​: 再次强调，此节点的核心功能是设置与当前执行关联的元数据。它本身不能读取这些数据。读取操作需要依赖 Code 节点和 $execution.customData 变量 。
• ​环境依赖 (Plan Dependency)​: 牢记此功能的可用性可能取决于你的 n8n 版本和计划 。在设计依赖此功能的工作流之前，请确认你的环境支持。
• ​严格的限制​: 必须遵守 Key (50 字符)、Value (255 字符, 必须是字符串) 以及总数 (最多 10 个) 的限制 。超出限制可能导致节点失败或数据丢失。
• ​非数据传递机制​: Execution Data不是设计用来在工作流的不同节点之间传递业务数据的。节点间的数据传递应该通过标准的 n8n 数据流（Items 从一个节点输出，连接到下一个节点的输入）来完成。Execution Data 主要用于附加关于执行本身的描述性信息，用于后续的追踪和筛选。
• ​覆盖行为​: 如果在同一次执行中，对同一个 Key 多次使用 Execution Data 节点进行设置，后面的值会覆盖掉前面的值。理解这一点对于使用它来更新状态标签等场景很重要。
• ​性能影响​: 虽然设置执行数据本身的操作通常很快，但如果 Value 是通过复杂的表达式动态生成的，表达式的计算可能会消耗一定资源。同时，存储大量的执行数据（如果执行频率非常高）可能会对 n8n 的数据库造成一定压力，尽管单个执行的数据量很小。

明确这些注意事项，可以帮助你更准确、高效地利用 Execution Data 节点，将其用在最合适的场景中。

第四章：比较数据集 (Compare Datasets)

节点概览：找出两份数据的“异同”

在许多业务场景中，我们需要比较两个相关的数据集，找出它们之间的差异和共同点。想象以下几种情况：

• 你有一份上个月的客户名单，还有一份这个月的最新名单，你想知道哪些是新客户？哪些客户流失了？哪些客户的信息（比如电话或地址）发生了变更？
• 你的 ERP 系统里记录着产品库存数量，同时你的电商网站前端也显示着库存，你需要核对两者是否一致，找出差异以便及时调整。
• 你维护着一个内部用户数据库，还需要与某个外部应用（如 Google Workspace）的用户列表保持同步，你需要找出哪些用户只存在于一端，或者两边都有但权限信息不匹配。

手动完成这些比较工作既耗时又容易出错。n8n 的比较数据集 (Compare Datasets) 节点正是为了解决这类问题而设计的自动化利器 。

这个节点的核心功能是接收两个独立的输入数据流（分别标记为 Input A 和 Input B），每个数据流都包含一系列的数据项 (Items)。然后，它会根据你指定的“匹配规则”（通常是基于某个能在两个数据集中唯一标识同一个实体的字段，如用户 ID、邮箱、产品 SKU 等），逐项进行比较。比较完成后，它会将结果分发到四个不同的输出分支 ：

1. ​In A Only​: 只存在于输入 A 中，但在输入 B 中找不到对应匹配项的数据。
2. ​In B Only​: 只存在于输入 B 中，但在输入 A 中找不到对应匹配项的数据。
3. ​Same​: 在 A 和 B 中都找到了匹配项，并且经过比较，两个数据项的所有（或指定要比较的）字段内容完全相同。
4. ​Different​: 在 A 和 B 中都找到了匹配项，但除了匹配字段外，至少有一个其他字段的内容在两者之间存在差异。

通过检查这四个分支的输出，你就能清晰地了解两个数据集之间的全部异同情况，并据此执行后续的操作（如同步数据、发送通知、更新记录等）。比较数据集 (Compare Datasets) 节点是 n8n 中用于数据核对、同步和差异分析的核心工具之一 。

参数配置与理解：定义比较规则与处理方式

配置比较数据集 (Compare Datasets) 节点的核心在于清晰地告诉 n8n 两件事：

1.如何识别两个数据集中“相同”的实体？(即，匹配的依据是什么？)
2.如果找到了匹配的实体，但它们的信息有差异，应该如何处理这些差异？以下是主要的参数配置项及其翔宇理解：

• ​匹配字段 (Fields to Match)​: 这是节点进行比较的基础。你需要指定用于在 Input A 和 Input B 之间建立关联的字段 。
  • Input A Field: 输入数据流 A 中，用作匹配标识的字段名称（键 Key）。例如，可以是 customerId 或 email。
  • Input B Field: 输入数据流 B 中，用作匹配标识的字段名称（键 Key）。这个名称​可以与 Input A Field 不同​。例如，A 中的是 customerId，而 B 中的是 user_id，只要它们代表的是同一个实体的标识符即可 。
  • ​翔宇关键提醒 (输入字段名，而非值或表达式!)​: 这是新手使用此节点时最常见的​错误点​！在这两个输入框中，你应该填写的是​字面上的字段名称 (Key)​，例如直接输入 customerId 或 user_id。绝对不要在这里使用 n8n 的表达式 {{ }} 来引用字段的值，比如写成 {{ $json.customerId }}。节点需要知道的是“用哪个名字的字段去匹配”，而不是“用这个具体的值去匹配”。社区中大量案例表明，错误地使用表达式是导致比较失败、所有数据都流向 “In A Only” 和 “In B Only” 分支的主要原因 。
  • ​多字段匹配​: 你可以点击 Add Fields to Match 按钮添加多个匹配字段对 。在这种情况下，只有所有指定的匹配字段对的值都相等时，两个数据项才被认为是匹配的。例如，你可以要求 firstName 和 lastName 两个字段都必须相同，才认为 A 和 B 中的两条记录是同一个人。
• ​差异处理 (When There Are Differences)​: 当节点根据匹配字段找到了 A 和 B 中的对应项后，它会进一步比较这两个匹配项的所有其他字段（除非在 Options 中排除了某些字段）。如果发现存在差异，这个参数就决定了最终从 “Different” 分支输出的数据项应该采用哪个来源的数据，或者如何组合它们 ：
  • Use Input A Version: 输出结果以 Input A 中的数据项为准。
  • Use Input B Version: 输出结果以 Input B 中的数据项为准。
  • Use a Mix of Versions: 允许你更精细地控制，可以指定某些字段的值来自 A，另一些字段的值来自 B（需要进一步配置）。
  • Prefer: 选择一个主要的数据来源（A 或 B），然后可以指定一个或多个“例外”字段，这些例外字段的值将从另一个数据来源获取。其他未指定的字段都来自主要来源。
  • Include Both Versions: 输出的数据项会同时包含来自 A 和 B 的数据，通常会将两者嵌套在不同的键下（例如 inputA 和 inputB），这使得输出结构变得更复杂，但提供了最全的信息。
  • ​翔宇建议​: 对于初学者和大多数常见的数据同步场景（例如，用系统 A 的数据更新系统 B），选择 Use Input A Version 或 Use Input B Version 通常是最直接和清晰的方式。其他选项提供了更大的灵活性，但也增加了配置的复杂性。
• ​模糊比较 (Fuzzy Compare)​:
  • 这是一个布尔开关选项。如果勾选此项，节点在比较字段值时会更加“宽容”，能够容忍一些细微的数据类型差异 。例如，数字 3 和字符串 "3" 会被视为相同；布尔值 true 和 数字 1 也可能被视为相同。
  • 如果​不勾选​（默认情况），节点会进行严格的比较，要求值和类型都完全一致。数字 3 和字符串 "3" 会被认为是不同的。
  • ​翔宇提示​: Fuzzy Compare 在处理来源不一致、数据类型可能混杂的数据时可能很方便，可以减少因微小类型差异而被误判为 “Different” 的情况。但它也可能掩盖潜在的数据质量问题。建议首先尝试精确比较（不勾选），只有当确实需要容忍类型差异时再考虑启用它，并清楚其可能带来的模糊性。
• ​比较过程详解​: 理解节点内部的工作流程有助于更好地配置和解读结果 ：
  1. ​匹配阶段​: 节点首先遍历 Input A 和 Input B 中的所有数据项，根据你设置的 Fields to Match 规则，尝试找到匹配对。找不到匹配项的数据会被分别归入 “In A Only” 或 “In B Only”。
  2. ​差异比较阶段​: 对于成功匹配上的每一对数据项 (Item A, Item B)，节点会接着比较它们内部所有的字段（除了在 Options -> Fields to Skip Comparing 中指定的字段外）。它会逐个字段比较 Item A 和 Item B 的值。
     • 如果所有被比较的字段值都​完全相同​（考虑到 Fuzzy Compare 的设置），这对数据项就被归类为 “Same”。
     • 如果至少有一个被比较的字段值​不同​，这对数据项就被归类为 “Different”。
  • ​关键点：键名也重要​: 这个比较过程不仅看字段的​值​，也隐含地依赖于字段的​键名​。如果两个数据集中表示相同概念的字段，其键名不同（例如 A 中是 phone，B 中是 phoneNumber），并且你没有在 Fields to Match 中正确映射它们（如果它们是匹配键的话），或者没有在后续处理中考虑到这种差异，那么即使它们的值相同，节点在进行字段级比较时也可能因为找不到对应的键而产生非预期的结果。社区案例 表明，键名不一致是导致数据被错误归类到 “In A Only” / “In B Only” 的一个潜在原因，即使你感觉数据内容是对应的。因此，在比较前使用 Rename Keys 节点统一关键字段的名称，通常是一个好的实践。

数据映射与表达式：指定比较的“身份证”

如前所述，正确配置比较数据集 (Compare Datasets) 节点的关键在于准确指定用于匹配的字段名。

• ​匹配字段 (Input A Field, Input B Field)​:
  • 必须直接填写输入数据项 json 对象中存在的字段名 (Key)。
    绝对不要使用表达式 {{ }} 来引用字段的值 。
  • 确保输入的字段名大小写正确，且在对应的数据流（Input A 或 Input B）中确实存在。
• ​数据结构要求​:
  • 输入到 Input A 和 Input B 的数据流都应该是包含多个数据项 (Items) 的列表（数组）。
  • 每个数据项的 json 对象中，必须包含你在 Fields to Match 中指定的那个（或那些）字段。
• ​节点选项 (Node Options)​: 除了核心参数，节点还提供了一些选项来微调比较行为 ：
  • ​要跳过比较的字段 (Fields to Skip Comparing)​:
    • 这是一个非常有用的选项。你可以输入一个或多个字段名（用逗号分隔）。当节点比较两个匹配上的数据项时，如果发现这些被指定的字段值不同，不会因此将这对数据项归类为 “Different”。
    • ​应用场景​: 比如你想比较两个客户列表的核心信息（姓名、邮箱、电话），但不想因为 last_updated_timestamp（最后更新时间戳）这个字段值的不同而将记录标记为有差异。你就可以在 Fields to Skip Comparing 中填入 last_updated_timestamp。这样，只要其他核心信息一致，即使时间戳不同，记录也会被归入 “Same” 分支。
    • ​示例数据说明​: 文档 中给出了一个例子：比较两个包含 person.name 和 person.language 的数据集，以 person.language 作为匹配字段。如果 Input A 是 {"person": {"name": "Stefan", "language": "de"}}，Input B 是 {"person": {"name": "Sara", "language": "de"}}，默认情况下它们会被认为是 “Different”（因为 name 不同）。但如果在 Fields to Skip Comparing 中加入 person.name，那么它们就会被认为是 “Same”（因为匹配字段 language 相同，而被跳过的 name 字段的差异被忽略了）。
  • ​禁用点表示法 (Disable Dot Notation)​:
    • 与排序 (Sort) 节点中的同名选项类似 。默认情况下（未勾选），n8n 允许你在 Fields to Match 和 Fields to Skip Comparing 中使用点 . 来指定嵌套对象中的字段，例如 address.street。
    • 如果你的字段名本身包含点 .（例如 product.category 是一个单一的键名，而不是 product 对象下的 category 键），并且你希望 n8n 将其视为一个整体名称，那么可以勾选此项。对于初学者，保持默认（不勾选）通常是合适的。

理解这些数据映射和选项的配置，可以帮助你更精确地控制比较逻辑，得到符合业务需求的比较结果。

应用场景：同步联系人、核对库存

比较数据集 (Compare Datasets) 节点的应用场景非常广泛，几乎所有涉及两方数据核对、同步或差异分析的需求都可以利用它来高效实现。以下是翔宇在实践中经常构建的一些典型工作流：

1. ​双向联系人同步 (CRM 与邮件列表)​:
   • ​场景​: 需要保持 CRM 系统（如 Salesforce , HubSpot）中的联系人信息与邮件营销平台（如 Mailchimp, SendGrid）中的订阅者列表同步。
   • ​流程​:
     • Input A: 从 CRM 获取所有联系人列表。
     • Input B: 从邮件营销平台获取所有订阅者列表。
     • Compare Datasets:
       • Fields to Match: email (假设 email 是唯一标识符)。
       • When There Are Differences: Use Input A Version (假设以 CRM 数据为准)。
   • ​后续处理​:
     • “In A Only” 输出 -> 这些联系人存在于 CRM 但不在邮件列表 -> 可能需要调用邮件平台的 API 将他们添加为订阅者。
     • “In B Only” 输出 -> 这些订阅者存在于邮件列表但不在 CRM -> 可能需要在 CRM 中创建新联系人，或者从邮件列表中移除（取决于业务规则）。
     • “Different” 输出 -> 两边都有，但信息（如姓名、电话、标签）不一致 -> 调用邮件平台的 API，使用来自 CRM 的数据更新这些订阅者的信息。
     • “Same” 输出 -> 信息一致，通常无需操作。
2. ​库存核对与同步 (ERP 与电商平台)​:
   • ​场景​: 需要确保 ERP 系统中记录的实际库存数量与在线销售平台（如 Shopify, Magento）上显示的库存数量保持一致。
   • ​流程​:
     • Input A: 从 ERP 系统导出或通过 API 获取产品库存列表 (SKU, Quantity)。
     • Input B: 从电商平台 API 获取产品库存列表 (SKU, Quantity)。
     • Compare Datasets:
       • Fields to Match: SKU (产品唯一编码)。
       • When There Are Differences: 可以选择 Use Input A Version (以 ERP 为准)，或者仅用于识别差异。
   • ​后续处理​:
     • “Different” 输出 -> 表示同一 SKU 在 ERP 和电商平台的库存数量不符 -> 需要触发一个动作，例如调用电商平台的 API 更新库存数量为 ERP 的值，或者生成一个报告通知库存管理员核查。
     • “In A Only” / “In B Only” -> 可能表示产品上下架状态不一致，也需要相应处理。
3. ​用户账户与权限同步 (内部数据库与外部应用)​:
   • ​场景​: 公司内部有一个主用户数据库，需要与员工使用的各种 SaaS 应用（如 Google Workspace, Microsoft 365, Slack ）的用户列表及权限保持同步。
   • ​流程​:
     • Input A: 从内部数据库获取用户列表及状态/权限信息。
     • Input B: 从目标应用 API 获取用户列表及状态/权限信息。
     • Compare Datasets:
       • Fields to Match: username 或 email。
   • ​后续处理​:
     • “In A Only” (内部有，应用无) -> 调用应用 API 创建新用户账户。
     • “In B Only” (应用有，内部无/已禁用) -> 调用应用 API 禁用或删除该用户账户。
     • “Different” (两边都有，但状态或权限不符) -> 调用应用 API 更新用户的状态或权限，使其与内部数据库一致。
4. ​监控数据变化 (网页抓取或 API 轮询)​:
   • ​场景​: 需要定期监控某个网页上的产品价格列表、某个 API 返回的数据列表，或者数据库中某个表的数据，以便在发生变化时得到通知或触发动作。
   • ​流程​:
     • Input A: 当前抓取或查询到的数据列表。
     • Input B: 上一次成功抓取或查询并保存下来的数据列表（例如，存储在 n8n 的 Static Data、数据库或文件中）。
     • Compare Datasets:
       • Fields to Match: 数据项的唯一标识符（如产品 ID, URL）。
   • ​后续处理​:
     • 检查 “In A Only” (新增项), “In B Only” (删除项), “Different” (修改项) 三个分支是否有输出。如果有，则说明数据发生了变化，可以触发发送邮件/Slack 通知、更新数据库、或执行其他相关操作。然后，将 Input A 的数据保存下来，作为下一次比较时的 Input B。

这些例子展示了比较数据集节点在自动化数据管理流程中的核心作用，它能够将复杂的数据比对逻辑简化为清晰的、可操作的步骤。

常见报错及解决方案：

在使用比较数据集 (Compare Datasets) 节点时，最常见的问题是比较结果与预期不符。以下是一些典型的问题及其排查方法：

• ​问题​: 明明感觉两个数据集中有应该匹配上的数据，但它们却分别出现在了 “In A Only” 和 “In B Only” 的输出分支中。
  • ​翔宇分析​:
    1. ​匹配字段配置错误​: 这是最可能的原因。你在 Fields to Match 的 Input A Field 或 Input B Field 中错误地使用了表达式 {{ }} 或输入了字段的​值​，而不是字段的名称 (Key)。节点无法理解你的匹配意图。
    2. ​匹配值不完全一致​: 你用来匹配的字段的值在 Input A 和 Input B 中实际上并不完全相同。可能存在肉眼难以察觉的差异，如：
       • ​隐藏的空格​: 字符串前后有多余的空格。
       • ​大小写不同​: 例如，”apple” 和 “Apple”。
       • ​数据类型不同​: 例如，数字 123 和字符串 "123"，并且你没有启用 Fuzzy Compare。
       • ​特殊字符或编码​: 存在不可见字符或编码差异。
    3. ​键名不一致​: 如前所述，即使匹配字段的值相同，但如果两个数据集中其他字段的键名存在显著差异，也可能影响比较逻辑，导致误判（虽然理论上匹配键相同应该能找到对，但这可能与其他因素耦合） 。
  • ​解决方案​:
    1. ​检查匹配字段配置​:确保在 Input A Field 和 Input B Field 中填写的是​字面上的、准确的字段名称 (Key)​，而不是值或表达式！
    2. ​仔细检查匹配值​: 在比较之前，最好对匹配字段的值进行清洗和标准化。使用 Set 节点或 Code 节点去除首尾空格 (trim())，统一大小写 (toLowerCase() 或 toUpperCase())。如果类型可能不一致，考虑启用 Fuzzy Compare，或者在比较前进行显式类型转换。
    3. ​统一键名​: 如果两个数据集的结构（键名）差异很大，建议在比较之前，先使用 Rename Keys 节点将关键字段的名称统一起来，使结构更一致。
• ​问题​: 两个数据项根据匹配字段成功匹配上了，并且预期它们是完全相同的，但它们却出现在了 “Different” 输出分支中。
  • ​翔宇分析​: 这意味着除了你指定的匹配字段外，至少还有另外一个字段的值在 Input A 和 Input B 之间存在差异。这个差异可能很细微。
  • ​解决方案​:
    1. ​详细对比​: 检查 “Different” 分支输出的数据。n8n 通常会提供关于哪些字段不同的信息（具体看节点输出结构）。仔细对比 Item A 和 Item B 的所有字段值，找出不一致的地方。
    2. ​忽略不重要字段​: 如果差异发生在你认为不重要或者预期会变化的字段上（例如 last_updated_timestamp, _version_number 等），请使用节点选项中的 Fields to Skip Comparing 功能，将这些字段名加入列表，以忽略它们的差异 。
    3. ​检查数据类型​: 即使值看起来一样，数据类型不同（如 5 vs "5"）在精确比较模式下也会导致差异。
    4. ​检查 Fuzzy Compare​: 如果你开启了 Fuzzy Compare，它可能未能覆盖所有你期望的模糊匹配情况。
• ​问题​: 节点运行非常缓慢，或者因超时、内存不足而失败。
  • ​翔宇分析​: 输入到 Input A 或 Input B（或两者）的数据集非常庞大，包含大量的 Items 和/或每个 Item 包含大量字段。比较操作需要将数据加载到内存中并进行两两匹配和字段级比较，这在数据量巨大时会非常消耗资源。
  • ​解决方案​:
    1. ​优化上游​: 检查产生 Input A 和 Input B 的上游节点。是否可以进行过滤，只获取需要比较的数据子集？例如，只比较过去 24 小时内有更新的记录。
    2. ​数据库层面优化​: 如果数据来自数据库，尽可能利用数据库的查询能力进行部分比较或筛选，减少传输到 n8n 的数据量。
    3. ​分批处理 (Batching)​: 尝试将大的数据集分成较小的批次进行比较。可以使用 Split In Batches 节点，然后在一个循环 (Loop) 中逐批进行比较。但这会增加工作流的复杂性。
    4. ​增加资源​: 如果是自托管 n8n，考虑增加服务器的内存 (RAM) 和 CPU 资源。如果是 n8n Cloud，可能需要升级到更高配置的计划。
    5. ​检查节点设置​: 确保没有进行不必要的复杂比较（例如，匹配字段过多，或者没有跳过不必要的字段比较）。

通过系统地排查这些常见问题，你可以更有效地利用比较数据集节点来完成数据核对任务。

注意事项：

为了确保比较数据集 (Compare Datasets) 节点能够准确、高效地完成任务，以下几点需要特别注意：

• ​匹配键的选择​: 选择用作 Fields to Match 的字段至关重要。它应该是：
  • ​唯一性​: 在每个数据集中都能唯一标识一个实体（或至少在你关心的范围内是唯一的）。
  • ​稳定性​: 这个字段的值不应该频繁变动。
  • ​可用性​: 在两个数据集中都普遍存在。 常用的匹配键包括用户 ID、邮箱地址、订单号、产品 SKU、数据库主键等。错误地选择匹配键会导致比较结果完全失去意义。
• ​数据清洗的重要性​: “垃圾进，垃圾出”。如果输入的数据本身就存在质量问题（如格式不统一、拼写错误、数据类型混乱），比较结果的准确性将大打折扣。在将数据送入比较节点之前，进行必要的数据清洗和标准化（例如，使用 Set, Rename Keys, Code 等节点）是非常推荐的最佳实践。
• ​理解 Fuzzy Compare 的影响​: 启用 Fuzzy Compare 可以提高对微小类型差异的容忍度，但也可能掩盖需要关注的数据类型不一致问题。务必清楚它何时适用，何时可能带来风险。
• ​性能瓶颈​: 对于大数据集的比较，性能可能成为一个显著问题。需要提前评估数据量，并考虑性能优化策略，如上游过滤、分批处理或增加运行资源。避免在资源不足的环境下尝试比较百万级的数据项。
• ​理解四个输出分支​: 必须清晰地理解 “In A Only”, “In B Only”, “Same”, “Different” 这四个输出分支各自代表的含义，并根据你的业务需求，将后续的处理逻辑正确地连接到相应的分支上。例如，同步操作可能主要关注 “In A Only”, “In B Only”, “Different” 三个分支。
• ​比较的是快照​: 比较数据集节点比较的是它接收到输入数据那一刻的两个“快照”。如果在这期间源头数据发生了变化，节点是无法感知的。这对于需要实时一致性的场景需要特别考虑。

遵循这些注意事项，可以帮助你最大限度地发挥比较数据集节点的价值，构建出可靠、准确的数据核对与同步流程。

第五章：加密 (Crypto)

节点概览：基础的数据“保险箱”

在设计和运行自动化工作流时，我们有时会接触到需要保护的数据，或者需要验证数据的真实性和完整性，亦或是需要为某些实体生成独一无二的标识。这时，n8n 的加密 (Crypto) 节点就提供了一套基础的密码学工具，如同一个随身携带的“数据安全工具箱”，里面包含了几种常用的“锁具”和“印章” 。

这个节点可以帮助你完成以下几类基础的密码学相关操作 ：

1. ​生成随机字符串 (Generate)​: 快速生成指定格式的随机文本串，例如用于创建临时密码、生成唯一会话 ID 或通用唯一标识符 (UUID)。
2. ​计算哈希 (Hash)​: 为一段文本或一个文件计算出固定长度的“数字指纹”（哈希值或摘要）。哈希值的主要用途是验证数据完整性（比较哈希值可以判断数据是否被篡改）和数据校验，有时也用于密码存储（存储哈希而不是明文）。
3. ​计算 HMAC (Hmac)​: 这是一种带密钥的哈希计算。只有知道相同密钥（Secret）的双方才能为相同的数据计算出相同的 HMAC 值。它常用于验证消息的完整性和来源真实性（消息认证码）。
4. ​生成数字签名 (Sign)​: 使用私钥 (Private Key) 对一段数据进行签名。其他人可以使用对应的公钥来验证签名，从而确认数据的来源的确是你，并且数据在签名后未被修改。这常用于 API 请求的身份验证等场景。

需要强调的是，加密 (Crypto) 节点提供的是基础性的密码学功能。它不是一个全能的加密解密工具 。它主要关注于哈希、消息认证和数字签名等领域，以及随机数生成。

加密 (Crypto) 节点是 n8n 提供的一个核心工具 ，用于在工作流中执行一些常见的、与数据安全、完整性验证和唯一标识生成相关的任务。

参数配置：生成、哈希、签名轻松搞定

配置加密 (Crypto) 节点的第一步是在 操作 (Action) 参数下拉菜单中选择你想要执行的具体功能。不同的 Action 会对应不同的参数选项 。

• ​操作 (Action)​:
  • ​生成随机字符串 (Generate)​:
    • Property Name: 必填。指定生成的随机字符串应该保存到输出数据项 json 对象中的哪个新字段名下。例如，填入 randomId。
    • Type: 必填。选择你想要生成的随机字符串的格式 。常用选项包括：
      • ASCII: 生成由可打印 ASCII 字符组成的随机字符串。
      • BASE64: 生成符合 Base64 编码规则的随机字符串。
      • HEX: 生成由十六进制字符（0-9, a-f）组成的随机字符串。
      • UUID: 生成一个符合 UUID (Universally Unique Identifier) v4 标准的通用唯一标识符。这是生成全局唯一 ID 的​推荐方式​。
  • ​哈希 (Hash)​: 计算输入数据的哈希值。
    • Type: 必填。选择要使用的哈希算法 。常见的有：
      • MD5: 速度快，但已被认为不安全，容易发生碰撞，不推荐用于安全相关场景。
      • SHA256: 目前广泛使用的安全哈希算法，输出 256 位（32 字节）哈希值。
      • SHA512: 比 SHA256 更安全，输出 512 位（64 字节）哈希值。
      • 还有其他 SHA3 系列等选项。通常建议使用 SHA256 或 SHA512。
    • Binary File: 布尔开关。如果你要哈希的数据是来自一个文件（例如，通过 Read Binary File 节点读取的），你需要打开此开关。如果只是哈希普通的文本字符串，保持关闭。
    • Value: 当 Binary File 关闭时，在此输入你要进行哈希计算的文本值。支持使用表达式 {{ }} 。
    • Binary Property Name: 当 Binary File 打开时，在此指定输入数据项中包含文件二进制数据的属性名称。对于 n8n 处理文件的标准节点（如 Read Binary File, HTTP Request 下载文件），这个属性名通常是 data 。
    • Property Name: 必填。指定计算出的哈希值应该保存到输出数据项 json 对象中的哪个新字段名下。例如，填入 fileHash。
    • Encoding: 必填。选择输出哈希值的编码格式 。通常是：
      • BASE64: 将原始的二进制哈希值编码为 Base64 字符串。
      • HEX: 将原始的二进制哈希值编码为十六进制字符串。Hex 格式更常见。
  • ​HMAC​: 计算带密钥的消息认证码。
    • 参数与 Hash 操作非常相似（同样有 Type, Binary File, Value, Binary Property Name, Property Name, Encoding），但额外增加​了一个关键参数 ：
    • Secret: 必填。在这里输入用于计算 HMAC 的​密钥 (Secret Key)​。这个密钥是一个字符串，必须对验证方保密。支持使用表达式或从凭证中获取。
  • ​签名 (Sign)​: 使用私钥对数据进行数字签名。
    • Value: 必填。输入你要进行签名的字符串数据。支持使用表达式 {{ }} 。
    • Property Name: 必填。指定生成的数字签名应该保存到输出数据项 json 对象中的哪个新字段名下。例如，填入 requestSignature。
    • Algorithm Name or ID: 必填。选择签名所使用的算法 。列表通常会包含基于 RSA、ECDSA 等的常见签名算法（如 RSA-SHA256）。你需要根据你的应用场景（例如，对接的 API 要求）选择正确的算法。
    • Encoding: 必填。选择输出签名的编码格式，通常是 BASE64 或 HEX 。
    • Private Key: 必填。在这里输入用于签名的私钥 (Private Key)文本 。私钥通常是 PEM 格式的多行文本。强烈建议不要直接将私钥粘贴在这里，而是将其存储在 n8n 的凭证 (Credentials) 系统中，然后通过表达式引用凭证来获取私钥，以确保安全。
• ​核心限制再强调：非通用加密/解密工具​: 翔宇必须再次重申这个关键点。加密 (Crypto) 节点提供的功能集中在哈希、HMAC、签名和随机生成上。它不能用来执行常见的​对称加密​（例如，使用 AES 算法和一个密钥来加密一段敏感文本，以便之后用同一个密钥解密）或​非对称加密​（例如，使用公钥加密数据，以便只有持有对应私钥的人才能解密）。
  • 如果你需要在 n8n 工作流中实现这类通用的数据加密或解密操作（比如加密存储在数据库中的敏感字段，或者解密从外部接收到的加密数据），你需要依赖 Code 节点，并利用其环境提供的底层密码学库（例如，在 n8n Cloud 或配置允许的自托管环境中，可以使用 Node.js 内置的 crypto 模块 ）来编写相应的加密/解密逻辑。
  • 混淆 Crypto 节点的用途，试图用它来做它设计之外的加密解密任务，是行不通的。
• ​AI 工具集成​: 文档 提到此节点可以作为 AI 工具使用。这意味着在 n8n 更高级的 AI Agent 框架 中，你可以让 AI 模型根据对话或任务上下文，决定调用 Crypto 节点来执行某个操作（比如生成一个随机 ID 或计算一个哈希）。这为构建更智能的自动化流程提供了可能，但超出了本基础教程的范围。

数据映射与表达式

在使用加密 (Crypto) 节点的 Hash, Hmac, Sign 这几个操作时，你需要为节点提供待处理的数据（“原料”）以及可能的密钥或私钥（“钥匙”）。这些输入都可以通过静态值或动态表达式来提供。

• ​输入值 (Value)​:
  • 对于 Hash, Hmac, Sign 操作，Value 参数是必需的（除非使用 Binary File 模式）。
  • 你可以直接在输入框中输入静态的文本字符串。
  • 更常见的是，你会使用表达式 {{ }} 从上游节点获取需要处理的数据。例如：
    • 计算用户密码的哈希（​注意：仅为示例，实际密码处理需更安全实践​）：Value: {{ $json.password }}
    • 为 API 请求生成签名，可能需要先将多个请求参数按照特定规则拼接成一个字符串，然后将这个拼接后的字符串通过表达式传入 Value。例如: Value: {{ "param1=" + $json.value1 + "&param2=" + $json.value2 }} (具体拼接规则需参照 API 文档)。
    • 对于 Generate 操作，没有 Value 输入，因为它只负责生成。
• ​密钥/私钥 (Secret, Private Key)​:
  • 对于 Hmac 操作，Secret 是必需的。对于 Sign 操作，Private Key 是必需的。
  • ​安全警告​:极不推荐直接将敏感的密钥或私钥以明文形式粘贴在节点的参数输入框中！这样做会将敏感信息暴露在工作流定义中，存在严重的安全风险。
  • ​推荐做法​:
    1. ​使用 n8n 凭证 (Credentials)​: 将你的 Secret Key 或 Private Key 安全地存储在 n8n 的凭证管理系统中 。例如，可以创建一个 Generic Credential 或使用特定类型的凭证。
    2. ​通过表达式引用凭证​: 在节点的 Secret 或 Private Key 输入框中，使用表达式来引用你创建的凭证。例如，如果你创建了一个名为 myApiSecret 的凭证，其中包含一个名为 secretKey 的字段，你可以这样引用：Secret: {{ $credentials.myApiSecret.secretKey }}。这样，实际的密钥值就不会出现在工作流 JSON 中。
  • ​直接输入 (仅限非敏感或测试场景)​: 如果密钥本身不是高度敏感的（例如，只是一个用于内部测试的共享密钥），或者在非常临时的调试场景下，你也可以直接输入静态文本。但请务必谨慎评估风险。
• ​二进制属性名 (Binary Property Name)​:
  • 当使用 Binary File 模式时，你需要指定包含文件二进制数据的属性名。这个名称通常是静态的，对应于上游文件处理节点（如 Read Binary File, HTTP Request 下载文件）输出的标准属性名，一般就是 data。
• ​输出属性名 (Property Name)​:
  • 所有操作（Generate, Hash, Hmac, Sign）都需要指定 Property Name，用于定义输出结果保存在数据项 json 对象中的哪个新键下。这个名称通常也是静态的，由你根据需要命名，例如 uuid, sha256Hash, hmacSignature, rsaSignature。

通过灵活运用表达式和凭证管理，你可以安全、动态地为 Crypto 节点提供所需的输入数据和密钥。

应用场景：生成唯一码、校验数据完整性

加密 (Crypto) 节点虽然功能基础，但在实际工作流中却有着不少实用的场景，尤其是在需要唯一性、完整性校验和基础认证的场合。

1. ​生成唯一标识符 (UUID)​:
   • ​场景​: 当你需要为新创建的记录（如新用户、新订单、新文档）生成一个全局唯一的 ID 时，避免使用可能重复的自增数字或简单随机数。
   • ​应用​: 使用 Generate 操作，选择 Type 为 UUID 。将生成的 UUID 保存到一个字段（如 userId, orderNumber, documentId），用作该记录在系统中的唯一主键或标识符。这在分布式系统或需要合并多源数据时尤其重要。
2. ​校验文件下载完整性​:
   • ​场景​: 你的工作流需要从网络下载文件（例如，使用 HTTP Request 节点 或专门的文件下载节点），你需要确保下载的文件与源文件完全一致，没有在传输过程中损坏或被篡改。
   • ​应用​: 文件提供方通常会同时提供文件的哈希值（如 SHA256）。在 n8n 中下载文件后（得到二进制数据），使用 Hash 操作，选择与提供方相同的算法（如 SHA256），打开 Binary File 开关，计算下载文件的哈希值。然后，使用 IF 节点比较计算出的哈希值与提供方给出的哈希值是否相等。如果相等，则文件校验通过；如果不等，则可能文件下载不完整或已被篡改，应触发错误处理或重试逻辑。
3. ​API 请求签名与认证​:
   • ​场景​: 你需要调用一个要求对请求进行签名的第三方 API。这种签名通常需要将请求的部分参数（有时包括时间戳、nonce 等）按照特定规则组合，然后使用预共享的密钥 (Secret) 计算 HMAC，或者使用你的私钥 (Private Key) 进行数字签名。
   • ​应用​:
     • ​HMAC 场景​: 使用 Hmac 操作 。先用 Set 节点或 Code 节点准备好待签名的字符串 (Base String)，然后将其传入 Value，将预共享的密钥（从凭证获取）传入 Secret，选择 API 指定的哈希算法（如 SHA256）和编码（如 Base64）。将生成的 HMAC 值保存到一个属性中。最后，在 HTTP Request 节点中，将这个 HMAC 值按照 API 要求添加到请求头 (Header) 或请求参数 (Query/Body) 中。
     • ​数字签名场景​: 使用 Sign 操作 。同样先准备好待签名的字符串传入 Value，选择 API 指定的签名算法（如 RSA-SHA256）和编码，将你的私钥（从凭证获取）传入 Private Key。将生成的签名添加到 HTTP Request 节点的请求中。
4. ​Webhook 请求验证​:
   • ​场景​: 你的 n8n 工作流通过 Webhook 节点 接收来自外部服务的事件通知。为了确保这些请求确实来自合法的服务而不是恶意伪造，许多服务会在发送 Webhook 时附加一个签名（通常是基于请求内容和预共享密钥计算的 HMAC）。
   • ​应用​: 在 Webhook 节点之后，获取到请求体 (Body) 和请求头 (Header) 中的签名值。使用 Hmac 操作，将收到的请求体（可能需要特定处理，如序列化为字符串）传入 Value，将预共享的密钥（存储在凭证中）传入 Secret，选择服务指定的算法。计算出你自己的 HMAC 值。然后，使用 IF 节点比较你计算出的 HMAC 值与请求头中提供的签名值是否严格相等。如果相等，则验证通过，继续处理请求；如果不等，则请求可能非法，应拒绝处理或记录安全事件。
5. ​生成简单的密码哈希 (基础场景，非高安全推荐)​:
   • ​场景​: 在一些内部工具或低风险应用中，需要存储用户密码，但绝对不能明文存储。
   • ​应用​: 可以使用 Hash 操作（推荐 SHA256 或 SHA512） 计算用户密码的哈希值。​重要​: 仅仅计算哈希是不够的，还需要配合加盐 (Salting)策略（为每个用户生成一个唯一的随机盐值，将盐值与密码拼接后再计算哈希，然后将盐值和哈希值一起存储）。加盐逻辑需要在 Crypto 节点之前通过 Generate (生成盐) 和 Set (拼接) 节点实现。验证密码时，需要取出存储的盐值，与用户输入的密码拼接，计算哈希，再与存储的哈希值比较。
   • ​翔宇警告​: 这种方式只提供了基础的保护。对于需要高安全性的应用，强烈建议使用专门的、经过安全审计的密码处理库（通常需要在 Code 节点中调用）或依赖专业的身份认证服务，而不是手动实现哈希逻辑。

通过这些应用场景，你可以看到 Crypto 节点如何在实际工作中为数据处理流程增加一层基础的安全性和可靠性保障。

常见报错及解决方案：加密解密失败？

在使用 Crypto 节点时，可能会遇到一些报错或结果不符合预期的情况。以下是一些常见问题及排查方向：

• ​报错​: 节点执行时报错，提示类似 “Invalid input”, “Bad parameter”, 或与特定算法相关的错误。
  • ​翔宇分析​:
    1. ​输入格式错误​: 传入 Value, Secret, Private Key 的数据格式不符合节点或所选算法的要求。例如，私钥格式不正确，或者需要哈希/签名的 Value 是 null 或 undefined。
    2. ​参数选择不当​: 选择的 Type (算法) 或 Encoding (编码) 不受支持，或者与输入数据的类型不匹配。
    3. ​文件模式配置错误​: 使用 Binary File 模式时，指定的 Binary Property Name 不正确，或者输入的 Item 中确实缺少该二进制属性。
  • ​解决方案​:
    1. ​检查输入​: 仔细核对所有输入参数的值和格式。确保 Value 有效。对于 Secret 和 Private Key，确保格式正确无误（特别是从凭证获取时）。
    2. ​核对参数​: 确认所选的算法 (Type) 和编码 (Encoding) 是有效的，并且是你需要的。
    3. ​验证文件模式​: 如果使用 Binary File，检查上游节点是否确实输出了包含指定二进制属性（通常是 data）的数据项。
• ​问题​: 计算出的 Hash / Hmac / Signature 值与预期（例如，与对方系统计算的值或文档示例）不一致。
  • ​翔宇分析​:
    1. ​输入 Value 不一致​: 最常见的原因。你用来计算的原始数据 (Value) 与对方使用的原始数据存在细微差异，即使肉眼看不出来。可能是：
       • ​编码不同​: 例如，UTF-8 vs. GBK。
       • ​换行符不同​: Windows (CRLF) vs. Linux/Mac (LF)。
       • ​隐藏字符​: 如空格、制表符、BOM 头等。
       • ​顺序不同​: 如果 Value 是通过拼接多个参数生成的，拼接的顺序或分隔符可能与对方不一致。
    2. ​密钥/私钥不匹配​: 使用的 Secret (用于 Hmac) 或 Private Key (用于 Sign) 与对方使用的不匹配。
    3. ​算法/编码不一致​: 选择的 Type (哈希算法/签名算法) 或 Encoding (输出编码格式 Base64/HEX) 与对方不一致。
    4. ​HMAC/签名细节​: 某些 HMAC 或签名实现可能对输入数据有特定的预处理要求（如特定的序列化方式）。
  • ​解决方案​:
    1. ​精确比对输入​:务必确保你提供给 Crypto 节点的 Value 与参照方使用的原始数据在字节层面完全一致。可以使用在线文本比较工具或编程方式进行严格比对。特别注意编码和换行符问题。
    2. ​核对密钥​: 确认你使用的 Secret 或 Private Key 准确无误。
    3. ​统一算法和编码​: 与对方确认并使用完全相同的算法和输出编码格式。
    4. ​查阅文档​: 仔细阅读对方（如 API 提供方）的文档，了解是否有关于数据预处理、拼接顺序、编码等的特殊要求。
• ​误解/错误尝试​: 尝试使用 Crypto 节点来解密数据（如 AES 解密），或者直接用它来​验证密码​（而不是生成哈希用于后续比对）。
  • ​翔宇分析​: 如前所述，Crypto 节点的设计目标不包括通用的解密功能，也不直接提供密码验证逻辑（它只生成哈希） 。
  • ​解决方案​:
    1. ​理解节点功能​: 重新审视 Crypto 节点提供的四种操作（Generate, Hash, Hmac, Sign）及其适用场景。
    2. ​寻求正确工具​: 对于解密需求，需要使用 Code 节点调用底层密码学库。对于标准的密码验证（比较用户输入和存储的哈希/盐），也需要在 Code 节点或专门的身份验证服务中实现逻辑。
• ​报错​: “Command failed:…” 或 “/bin/sh:…: not found” （虽然这更常出现在 Execute Command 节点 ，但如果 Crypto 节点内部依赖了某些命令行工具且环境缺失，理论上也可能发生）。
  • ​翔宇分析​: n8n 运行环境中缺少 Crypto 节点所依赖的某个底层库或工具。这在标准 n8n 环境中极少发生，但在高度定制或不完整的 Docker 环境中可能出现。
  • ​解决方案​: 确保你的 n8n 运行环境是完整且标准的。如果是自托管 Docker，检查基础镜像是否包含了所有必要的依赖。

通过理解这些潜在的问题和误区，你可以更准确地使用 Crypto 节点，并有效地排查遇到的困难。

注意事项：

在使用加密 (Crypto) 节点时，由于涉及到密码学操作和可能的敏感信息，务必将安全性放在首位，并注意以下事项：

• ​密钥安全是重中之重​:
  • Secret (用于 Hmac) 和 Private Key (用于 Sign) 是高度敏感的信息。绝对不要将它们以明文形式直接硬编码在节点的参数中。
  • ​最佳实践​: 务必使用 n8n 的凭证管理 (Credentials)系统来安全地存储和管理这些密钥 。在节点中通过表达式 {{ $credentials.yourCredentialName.keyField }} 来引用它们。这样可以避免敏感信息泄露在工作流定义或日志中。
• ​选择安全的算法​:
  • 对于哈希操作，避免使用已被认为不安全的算法，如 MD5 和 SHA1。优先选择SHA256或更强的算法（如 SHA512, SHA3 系列） 。
  • 对于签名和 HMAC，同样需要根据应用场景的安全要求选择足够强度的算法。
• ​明确节点功能边界​:
  • 再次强调，Crypto 节点不是通用的数据加密/解密工具 。不要误用它来尝试保护需要强加密（如 AES）的敏感数据内容本身。它的核心在于哈希、消息认证、数字签名和随机生成。
• ​理解操作的用途​:
  • 清晰地区分 Hash, Hmac, Sign 这三个操作的用途和安全目标：
    • Hash: 主要用于数据完整性校验和唯一标识（不可逆）。
    • Hmac: 用于验证消息完整性和来源（需要共享密钥）。
    • Sign: 用于验证消息完整性和来源（使用非对称密钥对，可公开验证）。
  • 不要混淆它们的适用场景。例如，不要用简单的 Hash 来做消息认证，应该用 Hmac。
• ​处理二进制数据​: 当操作涉及文件内容（Binary File 模式）时，确保上游节点正确地传递了二进制数据（通常在 data 属性中），并且下游节点能够正确处理 Crypto 节点输出的（通常是编码后的）结果。
• ​依赖环境​: 虽然 Crypto 节点是 n8n 核心内置节点，但其底层可能依赖操作系统或 Node.js 环境提供的密码学库。在标准 n8n 环境下通常没有问题，但在非标准或受限环境中需注意。

时刻牢记安全原则，谨慎配置和使用 Crypto 节点，可以有效利用其功能，同时避免引入不必要的风险。

总结

恭喜你坚持学习到这里！通过本篇深度教程，你已经系统地了解并掌握了 n8n 中五个非常实用且基础的数据处理节点：排序 (Sort)、重命名键 (Rename Keys)、执行数据 (Execution Data)、比较数据集 (Compare Datasets) 和 加密 (Crypto)。

你可以把这些节点想象成一把功能丰富的瑞士军刀中的不同工具。单独来看，每个工具（节点）的功能可能相对简单直接——排序、改名、打标签、做比较、盖个章。但正是这些基础功能的组合与灵活运用，赋予了你在无代码/低代码环境中强大地处理数据的能力。它们能够帮助你解决在构建自动化流程时遇到的各种关于数据整理、规范化、追踪、核对以及基础安全保障的常见问题。

翔宇希望通过这次学习，你能够深刻体会到 n8n 这类工具的魅力所在：即使你没有任何编程背景，也完全可以通过可视化、拖拽式的操作，有效地驾驭复杂的数据流，将重复、繁琐的数据处理工作自动化，从而解放你的时间和精力，专注于更有创造性的任务 。这正是无代码/低代码运动的核心价值——让技术赋能于每一个人。