写在前面：代码很酷，但别让“它”毁了你的服务器
作为 N8N大学 的主编，笔者见过太多开发者在自定义节点（Custom Node）上栽跟头。n8n 的生态非常开放，允许我们用 TypeScript/JavaScript 无限扩展功能，这很诱人。但这种开放性也是一把双刃剑。
很多新手觉得“反正是跑在自己服务器上的代码”，就随意引入第三方库、随意处理数据流。殊不知，n8n 的节点运行在同一个进程（Worker）中，一旦你在自定义节点里踩了安全红线，轻则导致整个 n8n 实例崩溃，重则造成服务器被入侵、数据泄露。
今天，笔者就以“学长”的身份，带你硬核拆解在开发 n8n 自定义节点时，那些绝对不能触碰的安全红线。这不是危言耸听，而是实战中的血泪教训。
红线一：无差别的第三方库依赖
在编写 Node.js 代码时，遇到功能需求，第一反应往往是 `npm install xxx`。但在 n8n 自定义节点中，这是极其危险的。
n8n 的核心机制是“进程内执行”。这意味着你引入的每一个依赖包，都会被加载到 n8n 的主内存中。如果你的节点依赖了一个包含已知漏洞（CVE）的库，或者依赖包体积过大（如引入了完整的 `puppeteer` 用于简单的 DOM 解析），不仅会拖慢 n8n 的启动速度，更会扩大整个系统的攻击面。
避坑指南： 尽量使用 Node.js 原生模块（如 `crypto`, `fs`, `path`）或 n8n 已内置的轻量级库（如 `axios`）。如果必须引入新库，请确保其来源可靠，且保持依赖树的精简。记住，你的节点不是独立的沙箱，它是宿主程序的一部分。
红线二：直接执行系统命令（Command Injection）
这是最致命的安全红线。在自定义节点中，绝对不要直接使用 `child_process.exec` 或 `child_process.spawn` 执行来自用户输入（Workflow 变量）的命令。
想象一下，你写了一个节点用来在服务器上创建文件，文件名来自前一个节点传来的参数。如果文件名是 `test; rm -rf /`，而你直接拼接字符串执行命令，后果不堪设想。
笔者建议： 永远不要信任任何外部数据。如果确实需要调用系统命令，必须对输入参数进行严格的白名单校验，或者使用参数化传递。但在 n8n 的场景下，最佳实践是：将系统操作逻辑封装在 API 中，而不是在节点内直接执行 Shell 命令。 让 n8n 调用 API，而不是让 n8n 成为黑客的 Shell。
红线三：缺少输入验证与类型转换
TypeScript 的优势在于类型安全，但在自定义节点的 `execute` 方法中，n8n 传入的 `items` 数据结构是动态的。如果你假设传来的字段一定存在，或者一定是字符串，你的节点就会在运行时抛出异常，导致整个工作流中断。
更糟糕的是，如果你直接将未验证的数据传递给数据库查询或模板引擎，可能会引发注入攻击或逻辑错误。
硬核防御： 在 `execute` 方法的开头，必须对所有依赖的字段进行防御性编程。使用 `NodeApiError` 来优雅地处理缺失字段，而不是让 Node.js 进程崩溃。
typescript
// 伪代码示例：正确的防御姿势
const inputData = items[0].json;
if (!inputData.userId) {
throw new NodeApiError(this.getNode(), '缺少必要的 userId 字段');
}
红线四：敏感数据硬编码
在开发调试阶段，图方便直接把 API Key、数据库密码写在代码里，这是新手最容易犯的错误。一旦代码提交到 Git 仓库，或者节点被导出分享，敏感信息就彻底泄露了。
n8n 有自己的凭据（Credentials）管理系统，支持加密存储。自定义节点必须通过 `this.getCredentials()` 来获取凭据，而不是在代码中写死字符串。
安全红线： 严禁在 `.ts` 或 `.js` 文件中出现 `const apiKey = 'sk-123456'` 这样的代码。这不仅违反了安全最佳实践，也会让你的 n8n 实例在启动时就被标记为高风险。
红线五：无限制的资源消耗（DoS 自攻自受）
自定义节点的代码是同步执行的，如果你在节点中写了一个死循环，或者在处理大文件时没有使用流（Stream）而是直接读取到内存（Buffer），你的 n8n 实例很快就会因为内存溢出（OOM）而崩溃。
这不仅影响当前的工作流，还会阻塞整个 n8n 的 Worker 进程，导致其他工作流也无法执行。
性能红线： 处理大文件时，务必使用流式处理。对于耗时的计算任务，考虑将其拆分为异步任务，或者设置合理的超时时间。永远不要在自定义节点中执行“无限循环”。
红线六：不恰当的错误处理与日志泄露
当节点出错时，n8n 会捕获错误并显示在界面上。如果你在抛出错误时，将包含敏感信息的整个对象（如包含密码的 `config` 对象）直接 `JSON.stringify` 打印出来，这些敏感信息就会暴露在 n8n 的日志和前端界面中。
日志规范： 在捕获异常时，只输出必要的调试信息。对于敏感字段（如 token、password），必须进行脱敏处理（如替换为 `***`）后再记录日志。使用 n8n 提供的标准错误处理机制，而不是将堆栈信息直接暴露给用户。
FAQ：自定义节点开发常见问题
1. 自定义节点会拖慢 n8n 的整体速度吗？
如果代码编写规范，影响微乎其微。但如果引入了重型依赖或执行了阻塞式 I/O 操作，确实会拖慢整个系统。建议使用异步编程和流式处理来优化性能。
2. 我可以在自定义节点中使用第三方 API 吗？
可以，且推荐。但请不要直接在节点中硬编码 API 密钥。应当创建对应的 Credentials 定义，并在节点中通过 `this.getCredentials()` 安全获取。
3. 如果节点代码出错，会影响其他工作流吗？
在单进程模式下，严重的运行时错误（如未捕获的异常）可能会导致 Worker 进程重启，从而短暂影响其他任务。在队列模式（Queue Mode）下，错误会被隔离在单个 Worker 中，影响较小。因此，严格的错误边界控制至关重要。
总结与资源
开发 n8n 自定义节点是极具创造力的工作，但安全永远是第一位的。记住，你的节点运行在 n8n 的核心进程中，任何疏忽都可能造成连锁反应。
核心红线回顾：
- 严格控制依赖包的引入。
- 绝对禁止执行未经验证的系统命令。
- 始终对输入数据进行验证和脱敏。
- 使用凭据系统管理敏感数据。
如果你想深入学习 n8n 节点开发，欢迎访问 N8N大学 (n8ndx.com)，这里有更多硬核的实战教程等着你。保持敬畏，代码才能行稳致远。
