常见错误处理

在使用 N8N 的过程中，可能会遇到各种错误。本指南汇总了最常见的错误及其解决方案，帮助你快速定位和解决问题。

🚨 连接和认证错误

1. API 连接失败

错误信息

Error: connect ECONNREFUSED 127.0.0.1:3000

常见原因

目标服务未运行
网络连接问题
防火墙阻拦
URL 地址错误

解决方案

// 1. 检查服务状态
curl -I https://api.example.com/health

// 2. 使用测试环境
// 先用 Postman 或 curl 测试 API

// 3. 添加错误处理
// 在 HTTP Request 节点中启用
Continue On Fail: true

// 4. 添加重试机制
Retry On Fail: 3
Retry Interval: 2000

2. 认证失败

错误信息

Error: 401 Unauthorized
Error: 403 Forbidden  
Error: Invalid API key

解决方案

// 1. 检查 API Key
console.log('Current API Key:', $env.API_KEY);

// 2. 验证认证格式
// Bearer Token
Authorization: Bearer {{ $env.ACCESS_TOKEN }}

// Basic Auth
Authorization: Basic {{ Buffer.from($env.USERNAME + ':' + $env.PASSWORD).toString('base64') }}

// 3. 检查权限范围
// 确保 API Key 有足够的权限执行操作

// 4. 刷新 Token
// 对于过期的 OAuth Token，添加刷新逻辑

3. SSL/TLS 证书错误

错误信息

Error: self signed certificate
Error: unable to verify the first certificate

解决方案

// 1. 在 HTTP Request 节点中禁用 SSL 验证（仅开发环境）
Ignore SSL Issues: true

// 2. 添加证书验证
// 在服务器部署时添加正确的 SSL 证书

// 3. 使用环境变量控制
{{ $env.NODE_ENV === 'development' ? false : true }}

📊 数据处理错误

1. JSON 解析错误

错误信息

Error: Unexpected token in JSON
Error: Cannot parse JSON

解决方案

// 1. 验证 JSON 格式
try {
  const data = JSON.parse($input.first().json.response);
  return [{ json: data }];
} catch (error) {
  console.log('JSON Parse Error:', error.message);
  console.log('Raw Data:', $input.first().json.response);
  return [{ json: { error: 'Invalid JSON' } }];
}

// 2. 处理空响应
const response = $input.first().json.response;
if (!response || response.trim() === '') {
  return [{ json: { error: 'Empty response' } }];
}

// 3. 清理数据
const cleanedResponse = response
  .replace(/^\uFEFF/, '') // 移除 BOM
  .trim();

2. 数据类型错误

错误信息

Error: Cannot read property 'length' of undefined
Error: $json.items is not a function

解决方案

// 1. 安全访问属性
const items = $json.items || [];
const itemCount = items.length;

// 2. 类型检查
if (Array.isArray($json.items)) {
  $json.items.forEach(item => {
    // 处理数组项
  });
} else {
  console.log('items is not an array:', typeof $json.items);
}

// 3. 使用可选链操作符
const userName = $json.user?.profile?.name || 'Unknown';

// 4. 类型转换
const numericValue = parseInt($json.stringValue) || 0;
const booleanValue = Boolean($json.value);

3. 表达式语法错误

错误信息

Error: Unexpected token
Error: ReferenceError: variable is not defined

解决方案

// ❌ 错误写法
{{ $json.name + "的订单" }}  // 中文字符可能导致问题

// ✅ 正确写法  
{{ $json.name + '的订单' }}   // 使用单引号

// ❌ 错误写法
{{ $json.list.0.name }}       // 数组访问错误

// ✅ 正确写法
{{ $json.list[0].name }}      // 正确的数组访问

// ❌ 错误写法
{{ $json.date > "2024-01-01" }}  // 字符串比较

// ✅ 正确写法
{{ new Date($json.date) > new Date("2024-01-01") }}

🔄 工作流执行错误

1. 内存溢出

错误信息

Error: JavaScript heap out of memory
Error: Maximum call stack size exceeded

解决方案

// 1. 分批处理大数据
const batchSize = 100;
const items = $input.all();

for (let i = 0; i < items.length; i += batchSize) {
  const batch = items.slice(i, i + batchSize);
  // 处理批次数据
  await processBatch(batch);
}

// 2. 清理不需要的数据
return items.map(item => ({
  json: {
    // 只保留必要字段
    id: item.json.id,
    name: item.json.name
    // 移除大型数据字段
  }
}));

// 3. 使用流式处理
// 对于大文件，使用流式读取而不是一次性加载

2. 超时错误

错误信息

Error: Timeout
Error: Request timeout

解决方案

// 1. 增加超时时间
// 在 HTTP Request 节点中设置
timeout: 30000  // 30秒

// 2. 异步处理
// 将长时间任务分解为多个步骤

// 3. 使用 Webhook 回调
// 对于长时间运行的任务，使用异步模式
{
  "taskId": "12345",
  "callbackUrl": "https://your-n8n.com/webhook/task-complete"
}

3. 循环依赖

错误信息

Error: Circular dependency detected
Error: Maximum execution depth reached

解决方案

// 1. 检查工作流连接
// 确保没有形成循环连接

// 2. 添加循环计数器
let loopCount = $node["Function"].getWorkflowStaticData('node').loopCount || 0;
loopCount++;

if (loopCount > 100) {
  throw new Error('Maximum loop count reached');
}

$node["Function"].getWorkflowStaticData('node').loopCount = loopCount;

// 3. 使用条件退出
if ($json.shouldStop || $json.iteration > 10) {
  return [];  // 停止执行
}

🗄️ 数据库错误

1. 连接失败

错误信息

Error: connect ECONNREFUSED
Error: Access denied for user
Error: Database does not exist

解决方案

// 1. 检查连接参数
const config = {
  host: $env.DB_HOST,
  port: $env.DB_PORT || 3306,
  database: $env.DB_NAME,
  user: $env.DB_USER,
  password: $env.DB_PASSWORD
};

// 2. 测试连接
// 使用简单查询测试连接
SELECT 1 as test;

// 3. 检查防火墙和网络
// 确保数据库端口对 N8N 开放

// 4. 验证凭据
// 在数据库中直接验证用户名密码

2. SQL 语法错误

错误信息

Error: You have an error in your SQL syntax
Error: Column 'xxx' doesn't exist

解决方案

-- 1. 使用参数化查询
SELECT * FROM users WHERE id = {{ $json.userId }};

-- 2. 处理特殊字符
SELECT * FROM users WHERE name = '{{ $json.name.replace(/'/g, "''") }}';

-- 3. 验证字段存在
-- 在执行前检查表结构
DESCRIBE users;

-- 4. 使用安全的字段引用
SELECT `user_id`, `user_name` FROM `users`;

3. 数据类型不匹配

错误信息

Error: Data truncated
Error: Incorrect integer value

解决方案

// 1. 数据类型转换
const userId = parseInt($json.userId) || 0;
const amount = parseFloat($json.amount) || 0.0;
const isActive = Boolean($json.isActive);

// 2. 数据验证
if (isNaN(userId) || userId <= 0) {
  throw new Error('Invalid user ID');
}

// 3. 使用适当的数据类型
INSERT INTO orders (user_id, amount, order_date) 
VALUES (
  {{ parseInt($json.userId) }},
  {{ parseFloat($json.amount) }},
  '{{ new Date($json.orderDate).toISOString().slice(0, 19).replace('T', ' ') }}'
);

🔒 权限和安全错误

1. 文件权限错误

错误信息

Error: EACCES: permission denied
Error: ENOENT: no such file or directory

解决方案

# 1. 检查文件权限
ls -la /path/to/file

# 2. 修改权限
chmod 644 /path/to/file
chown n8n:n8n /path/to/file

# 3. 创建目录
mkdir -p /path/to/directory

2. 环境变量未设置

错误信息

Error: Environment variable 'API_KEY' is not set
Error: $env.API_KEY is undefined

解决方案

// 1. 检查环境变量
const apiKey = $env.API_KEY;
if (!apiKey) {
  throw new Error('API_KEY environment variable is required');
}

// 2. 提供默认值
const apiUrl = $env.API_URL || 'https://api.example.com';

// 3. 验证关键变量
const requiredVars = ['API_KEY', 'DATABASE_URL', 'WEBHOOK_SECRET'];
requiredVars.forEach(varName => {
  if (!process.env[varName]) {
    throw new Error(`${varName} environment variable is required`);
  }
});

🛠️ 调试技巧

1. 使用日志输出

// 在 Function 节点中添加详细日志
console.log('Input data:', JSON.stringify($input.all(), null, 2));
console.log('Processing step 1 completed');
console.log('Final result:', result);

// 使用条件日志
if ($env.NODE_ENV === 'development') {
  console.log('Debug info:', debugData);
}

2. 数据检查

// 检查数据结构
const data = $input.first().json;
console.log('Data type:', typeof data);
console.log('Data keys:', Object.keys(data));
console.log('Array length:', Array.isArray(data.items) ? data.items.length : 'Not an array');

// 验证必需字段
const requiredFields = ['id', 'email', 'name'];
const missingFields = requiredFields.filter(field => !data[field]);
if (missingFields.length > 0) {
  throw new Error(`Missing required fields: ${missingFields.join(', ')}`);
}

3. 错误恢复

// 实现错误恢复逻辑
try {
  // 尝试主要逻辑
  const result = await mainProcess(data);
  return [{ json: result }];
} catch (error) {
  console.log('Main process failed:', error.message);
  
  // 尝试备用方案
  try {
    const fallbackResult = await fallbackProcess(data);
    return [{ json: { ...fallbackResult, warning: 'Used fallback method' } }];
  } catch (fallbackError) {
    // 记录错误并返回最小响应
    console.log('Fallback also failed:', fallbackError.message);
    return [{ json: { error: true, message: 'All processing methods failed' } }];
  }
}

📋 错误预防清单

开发阶段

验证所有 API 端点和认证
测试边界条件和异常数据
添加适当的错误处理
使用环境变量管理配置
实现数据验证逻辑

部署阶段

运行阶段

通过系统性地了解和预防这些常见错误，你可以构建更稳定、更可靠的 N8N 工作流。记住，错误是学习和改进的机会！