【n8n教程】：Rename Keys 节点，让数据在不同系统间流动时保持一致

什么是 Rename Keys 节点？

在构建自动化工作流时，你经常会遇到这样的情况：来自不同应用的数据格式不一致。比如，一个系统称呼"名字"为 first_name，而另一个系统称它为 firstName。这时，Rename Keys 节点就派上用场了！

Rename Keys 节点的核心功能是重命名 JSON 对象中的键（字段名）。它能帮你快速将旧的键名转换为新的键名，确保数据在不同系统间流动时保持一致。

Rename Keys 节点的三大工作模式

1. 标准模式（推荐新手使用）

逐个指定要重命名的键：

• 当前键名：输入你想要重命名的原始键名
• 新键名：输入你想要的新名称

2. 正则表达式模式（高级玩法）

使用正则表达式批量重命名符合模式的键：

• 正则表达式：编写表达式来匹配多个键
• 替换为：指定替换后的新名称
• 区分大小写：控制匹配是否区分大小写
• 最大深度：设置重命名的层级深度（-1为无限，0为仅顶层）

3. 高级特性提示

⚠️ 重要提示：使用正则表达式时要小心，它会影响所有符合条件的键，包括你已经重命名过的键！

实战案例：构建你的第一个 Rename Keys 工作流

场景描述

你从一个 API 获取用户数据，格式如下：

{
  "first_name": "John",
  "last_name": "Doe",
  "user_email": "john.doe@example.com",
  "phone_number": "+1-555-0123"
}

但你的 CRM 系统期望的格式是：

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-0123"
}

解决方案：完整的可执行工作流

将下面的 JSON 工作流复制，然后在 n8n 中：

1. 点击右上角的三个点 (...)
2. 选择 Import from File 或直接粘贴 JSON 到画布
3. 点击 Import

{
  "name": "用户数据键值转换工作流",
  "nodes": [
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "7e2e5be4-91d5-4a49-9d65-59e56cce9b30",
              "name": "first_name",
              "value": "John",
              "type": "string"
            },
            {
              "id": "3d8c9f12-42a3-4b5e-8a2d-71f6c9e2d4b1",
              "name": "last_name",
              "value": "Doe",
              "type": "string"
            },
            {
              "id": "9c1a7f83-5b2c-4e9d-a1f6-82g7d0f3e5c2",
              "name": "user_email",
              "value": "john.doe@example.com",
              "type": "string"
            },
            {
              "id": "4d9b8g94-6c3d-5f0e-b2g7-93h8e1g4f6d3",
              "name": "phone_number",
              "value": "+1-555-0123",
              "type": "string"
            }
          ]
        }
      },
      "type": "n8n-nodes-base.set",
      "typeVersion": 2,
      "position": [380, 200],
      "name": "设置初始数据"
    },
    {
      "parameters": {
        "mode": "define",
        "toRename": {
          "renameOperations": [
            {
              "currentName": "first_name",
              "newName": "firstName"
            },
            {
              "currentName": "last_name",
              "newName": "lastName"
            },
            {
              "currentName": "user_email",
              "newName": "email"
            },
            {
              "currentName": "phone_number",
              "newName": "phone"
            }
          ]
        }
      },
      "type": "n8n-nodes-base.renameKeys",
      "typeVersion": 1,
      "position": [680, 200],
      "name": "重命名键"
    },
    {
      "parameters": {},
      "type": "n8n-nodes-base.noOp",
      "typeVersion": 1,
      "position": [980, 200],
      "name": "查看结果"
    }
  ],
  "connections": {
    "设置初始数据": {
      "main": [
        [
          {
            "node": "重命名键",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "重命名键": {
      "main": [
        [
          {
            "node": "查看结果",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": true,
  "settings": {}
}

工作流说明

第一步：设置初始数据

• 使用 Set 节点创建包含旧格式的数据
• 这模拟了从 API 接收的真实数据

第二步：重命名键

• 模式：选择 "define"（标准模式）
• 添加新键：为每个需要重命名的键添加一行
- • first_name → firstName
- • last_name → lastName
- • user_email → email
- • phone_number → phone

第三步：查看结果

• NoOp 节点用来展示最终数据（可选）
• 运行工作流后，检查输出数据是否已正确重命名

执行结果

运行此工作流后，你会看到数据被成功转换：

输入（来自第一个节点）：

[
  {
    "first_name": "John",
    "last_name": "Doe",
    "user_email": "john.doe@example.com",
    "phone_number": "+1-555-0123"
  }
]

输出（来自 Rename Keys 节点）：

[
  {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-0123"
  }
]

三个常见使用场景

场景 1：API 数据标准化

从多个 API 获取数据时，每个 API 的字段命名都不同。使用 Rename Keys 将它们统一为你的内部标准。

示例：

• Shopify API 返回：customer_first_name → 转换为 → firstName
• WooCommerce API 返回：billing_first_name → 转换为 → firstName

场景 2：准备导入到第三方系统

不同的系统有不同的数据字段要求。在导入前重命名键，避免数据映射出错。

示例：

• 你的系统字段：staff_id
• HR 系统要求：employee_id
• Rename Keys 搞定：staff_id → employee_id

场景 3：代码风格转换

在 snake_case（下划线命名）和 camelCase（驼峰命名）之间快速转换。

示例：

• 数据库字段：created_at, updated_at, user_status
• JavaScript 风格：createdAt, updatedAt, userStatus

高级技巧：使用正则表达式批量重命名

如果你需要一次性重命名许多遵循相同模式的键，正则表达式会非常高效。

示例：将所有下划线命名转为驼峰命名

• 正则表达式：_(.)
• 替换为：使用捕获组 $1（需要 JavaScript 支持）
• 结果：user_name → userName

⚠️ 提示：在使用正则表达式前，先在标准模式中测试你的用例，确保你完全理解其行为。

最佳实践总结

✅ DO（应该做）

1. 始终在 Rename Keys 节点之前使用 Set 或 Edit Fields 节点来验证数据结构
2. 为你的键命名建立清晰的命名规范（如 camelCase 或 snake_case）
3. 在生产环境前，用真实数据测试你的工作流
4. 对复杂的重命名操作使用描述性的节点名称

❌ DON'T（不应该做）

1. 不要在正则表达式模式中盲目信任自动转换
2. 不要尝试在一个节点中处理过度复杂的重命名逻辑
3. 不要忘记检查重命名后的数据是否被下一个节点正确识别
4. 不要在数组内的对象上直接使用 Rename Keys（改用 Map 或循环）

速查表：节点参数

参数	说明	示例
当前键名	原始的键名	`user_email`
新键名	重命名后的键名	`email`
正则表达式	匹配多个键的表达式	`_`
替换为	新名称的替换模式	空值或特定前缀
区分大小写	是否区分大小写	ON/OFF
最大深度	重命名的嵌套层级	-1（无限）/ 0（仅顶层）

常见问题解答

Q: Rename Keys 可以处理嵌套的 JSON 对象吗？
A: 可以！通过设置正确的最大深度参数，你可以深入到嵌套对象中重命名键。

Q: 如果我有 100 个字段需要重命名怎么办？
A: 使用正则表达式模式会更高效。或者考虑使用 Function 节点来编写自定义 JavaScript 脚本。

Q: 重命名后能不能保留原始字段？
A: Rename Keys 只重命名，不保留原始字段。如果需要保留，先使用 Duplicate 节点或手动在 Set 节点中复制字段。

Q: 在数组处理中如何使用 Rename Keys？
A: 需要结合 Split Out（分割）和 Loop 节点，或者在 Map 节点中使用。

官方文档^[1]
n8n系列教程^[2]

引用链接

[1] 官方文档: https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.renamekeys/
[2] n8n系列教程: https://www.undsky.com/blog/?category=n8n%E6%95%99%E7%A8%8B#