【n8n教程】：自定义变量，让你的工作流更加灵活高效

在 n8n 的世界里，变量（Variables） 是一个强大的功能，它允许你存储和重复使用值，使工作流更加灵活、可维护性更强。无论是 API 密钥、用户信息，还是需要在多个工作流中共享的配置值，变量都能轻松应对。

什么是 n8n 变量

n8n 变量是一种只读存储机制，用于保存你想在工作流中重复使用的值。它们在工作流执行时被替换为实际值，使你无需硬编码就能轻松管理配置和敏感信息。

变量的核心特点

• ✅ 易于维护：集中管理所有配置值
• ✅ 跨工作流使用：某些变量可以在所有工作流中共享
• ✅ 安全存储：避免在工作流中暴露敏感信息
• ✅ 字符串类型：所有变量都以字符串形式存储
• ✅ 灵活范围：支持全局和项目级别的作用域

变量的作用域

全局变量 (Global Variables)

全局变量对你的 n8n 实例中的所有项目 都可用。这意味着任何人都可以在任何工作流中访问它们。

适用场景：

• 存储公司通用的 API 端点
• 保存所有工作流都需要的基础配置
• 跨项目共享的常用数据

项目变量 (Project-Scoped Variables)

项目变量仅在 特定项目内 可用。只有该项目中的工作流才能访问这些变量。

适用场景：

• 项目特定的 API 密钥
• 特定客户端的配置
• 需要隔离的敏感信息

重要提示： 项目变量需要 n8n 版本 1.118.0 及以上。

变量优先级

当项目级变量和全局变量同名时，项目级变量优先。这确保了项目特定的设置会覆盖全局默认值。

创建变量

前提条件

• 需要 实例所有者或管理员 权限
• n8n 自主托管企业版或 Pro 云计划

步骤 1：访问变量管理界面

1. 登录你的 n8n 实例
2. 进入 概览页面 或 特定项目
3. 点击左侧菜单中的 Variables 选项卡

步骤 2：添加新变量

1. 在 Variables 选项卡中，点击 Add Variable 按钮
2. 你将看到两个输入字段

步骤 3：配置变量

Key（键） - 变量的名称，最大 50 个字符

• 例如：API_KEY、SLACK_WEBHOOK、EMAIL_FROM
• 只支持字母、数字和下划线（A-Z, a-z, 0-9, _）

Value（值） - 变量的实际值，最大 1000 个字符

• 例如：https://api.example.com、xoxb-1234567890...

步骤 4：设置作用域（仅在概览页创建时显示）

Global - 变量对整个实例可用
Project - 变量仅在特定项目可用（选择相应项目）

从项目页创建时，作用域自动设为该项目。

步骤 5：保存变量

点击 Save 按钮。变量现在可在你的工作流中使用。

在工作流中使用变量

在代码节点中使用

在 Code node 中，你可以直接访问变量。以下是常见的访问方式：

// 访问变量
const apiKey = $env.API_KEY;
const slackWebhook = $env.SLACK_WEBHOOK;

// 在代码中使用
console.log(`Using API Key: ${apiKey}`);

在表达式中使用

在任何支持表达式的字段中，使用以下格式：

{{ $env.VARIABLE_NAME }}

具体例子：

• HTTP 请求的授权头：{{ $env.API_KEY }}
• Slack 消息内容：Hello {{ $env.USERNAME }}
• 数据库连接字符串：{{ $env.DB_CONNECTION_STRING }}

支持表达式的字段

大多数 n8n 节点都支持在以下字段中使用变量：

• 文本字段
• URL 字段
• API 头和授权信息
• 条件分支中的比较值
• 任何接受动态输入的字段

访问变量时注意事项

1. 变量作为字符串：所有变量都是字符串类型，如需其他类型，在使用时进行类型转换
2. 变量不存在时：如果变量未定义，表达式会返回 undefined，工作流不会自动失败
3. 只读特性：变量只能通过 UI 修改，不能在工作流中直接更改

编辑和删除变量

编辑变量

1. 在 Variables 选项卡中，悬停于要修改的变量上
2. 点击显示的 Edit 按钮
3. 修改 Key 或 Value
4. 点击 Save

删除变量

1. 在 Variables 选项卡中，悬停于要删除的变量上
2. 点击显示的 Delete 按钮
3. 确认删除

实战案例：自动化邮件发送工作流

场景描述

你需要创建一个工作流，该工作流从 Webhook 接收数据，然后通过 SMTP 服务发送邮件。为了安全和可维护性，所有敏感信息（如 SMTP 服务器地址、邮箱等）都应该存储为变量。

第一步：创建必要的变量

在 n8n 中创建以下变量：

Key	Value	说明
`SMTP_HOST`	`smtp.gmail.com`	SMTP 服务器地址
`SMTP_PORT`	`587`	SMTP 端口
`EMAIL_FROM`	`noreply@company.com`	发件人邮箱
`EMAIL_PASSWORD`	`your_app_password`	邮箱密码或应用专用密码
`COMPANY_NAME`	`My Company`	公司名称

第二步：工作流结构

Webhook Trigger → Process Data → Send Email → Response

第三步：完整可执行工作流代码

{
  "name": "Email Automation with Variables",
  "nodes": [
    {
      "parameters": {
        "path": "send-email",
        "responseMode": "onReceived"
      },
      "id": "webhook",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [
        250,
        300
      ]
    },
    {
      "parameters": {
        "mode": "manual",
        "fields": {
          "values": [
            {
              "name": "recipientEmail",
              "value": "= $json.body.email"
            },
            {
              "name": "recipientName",
              "value": "= $json.body.name"
            },
            {
              "name": "emailSubject",
              "value": "= 'Welcome to ' + $env.COMPANY_NAME"
            }
          ]
        }
      },
      "id": "set_data",
      "name": "Extract & Process Data",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3,
      "position": [
        450,
        300
      ]
    },
    {
      "parameters": {
        "fromEmail": "= $env.EMAIL_FROM",
        "toEmail": "= $json.recipientEmail",
        "subject": "= $json.emailSubject",
        "textContent": "= 'Hello ' + $json.recipientName + ',\\n\\nWelcome to ' + $env.COMPANY_NAME + '!\\n\\nBest regards,\\n' + $env.COMPANY_NAME + ' Team'",
        "protocol": "tls",
        "host": "= $env.SMTP_HOST",
        "port": "= parseInt($env.SMTP_PORT)",
        "user": "= $env.EMAIL_FROM",
        "password": "= $env.EMAIL_PASSWORD"
      },
      "id": "send_email",
      "name": "Send Email",
      "type": "n8n-nodes-base.emailSend",
      "typeVersion": 1,
      "position": [
        650,
        300
      ]
    },
    {
      "parameters": {
        "mode": "manual",
        "fields": {
          "values": [
            {
              "name": "status",
              "value": "success"
            },
            {
              "name": "message",
              "value": "Email sent successfully"
            }
          ]
        }
      },
      "id": "response",
      "name": "Return Response",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3,
      "position": [
        850,
        300
      ]
    }
  ],
  "connections": {
    "webhook": {
      "main": [
        [
          {
            "node": "set_data",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "set_data": {
      "main": [
        [
          {
            "node": "send_email",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "send_email": {
      "main": [
        [
          {
            "node": "response",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

第四步：工作流详解

1. Webhook 触发节点

接收来自外部系统的 POST 请求，数据格式：

{
  "email": "user@example.com",
  "name": "John Doe"
}

2. 提取和处理数据节点

• 从 Webhook 中提取邮箱和姓名
• 使用 $env.COMPANY_NAME 变量组成邮件主题
• 为后续节点准备好的数据

3. 发送邮件节点

• 使用所有定义的变量：EMAIL_FROM、SMTP_HOST、SMTP_PORT、EMAIL_PASSWORD
• 组成个性化的邮件内容，包含公司名称

4. 返回响应节点

返回成功状态给调用方

第五步：测试工作流

1. 复制上述 JSON 代码
2. 在 n8n 中创建新工作流
3. 使用导入功能粘贴 JSON 代码
4. 配置你的变量值
5. 激活工作流
6. 使用工具如 Postman 或 curl 测试 Webhook：

curl -X POST http://your-n8n-url/webhook/send-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "name": "Test User"
  }'

工作流优势

✅ 安全：敏感信息存储在变量中，不暴露在工作流中
✅ 易于迁移：更换环境时只需修改变量值
✅ 可维护：集中管理所有配置
✅ 可重用：其他工作流也可以使用相同的变量

常见问题

Q1: 如果变量值为空怎么办？

A: n8n 会将其视为 undefined。工作流不会自动失败，但可能导致后续节点出错。建议在使用变量前进行验证。

if ($env.API_KEY === undefined) {
  throw new Error('API_KEY variable is not set');
}

Q2: 可以在工作流中修改变量吗？

A: 不行。变量是只读的。如果需要在工作流中设置和访问自定义数据，请使用 Workflow Static Data 功能。

Q3: 变量支持哪些字符？

A: 只支持：

• 大写字母 (A-Z)
• 小写字母 (a-z)
• 数字 (0-9)
• 下划线 (_)

Q4: 全局变量和项目变量的区别是什么？

• 全局变量：对实例中所有项目都可用
• 项目变量：仅在特定项目内可用
• 优先级：项目变量会覆盖同名的全局变量

Q5: 如何在不同环境（开发、测试、生产）中使用不同的变量值？

A: 创建相同 Key 的项目变量，在各个环境对应的项目中设置不同的 Value 值。每个项目的工作流会使用该项目的变量值。

最佳实践

1. 命名规范

使用大写字母和下划线，使变量名清晰明确：

• ✅ API_KEY_SLACK
• ✅ SMTP_HOST
• ❌ apiKey （不符合约定）
• ❌ api-key （包含不支持的字符）

2. 安全性

• 存储所有敏感信息（API 密钥、密码、令牌）为变量
• 定期轮换敏感变量值
• 限制访问权限给必要的用户

3. 文档记录

为每个变量添加描述和用途说明，便于团队理解：

• 用途是什么
• 在哪些工作流中使用
• 更新频率如何

4. 模块化设计

• 将相关变量分组（如 SMTP 相关、API 相关）
• 使用项目变量隔离不同客户端的配置
• 保持全局变量精简

总结

n8n 的自定义变量功能为你的自动化工作提供了一个强大的配置管理系统。通过合理使用全局和项目级变量，你可以创建更加安全、易维护、可扩展的工作流。

关键要点：

• 📌 变量支持全局和项目级别的作用域
• 📌 所有变量都是字符串类型
• 📌 使用 {{ $env.VARIABLE_NAME }} 在表达式中访问
• 📌 变量是只读的，只能通过 UI 修改
• 📌 项目变量优先级高于全局变量

现在，你已经掌握了 n8n 变量的核心知识！开始在你的工作流中应用这些技巧，让自动化更加高效、安全、可维护。

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

引用链接

[1] 官方文档: https://docs.n8n.io/code/variables/
[2] n8n系列教程: https://www.undsky.com/blog/?category=n8n%E6%95%99%E7%A8%8B#