写在前面：为什么你的 n8n 流程总是卡在“401 Unauthorized”？
大家好，我是 N8N大学 的主编。今天不聊高大上的大模型接入，也不谈复杂的业务逻辑，只想和大家聊聊 n8n API 集成中最让人头秃的环节——认证。
相信很多刚上手 n8n 的朋友，都经历过这样的绝望：明明 API 地址没输错，参数也对了，但一运行就是 401 Unauthorized 或者 403 Forbidden。看着红色的报错提示，你甚至开始怀疑人生：到底是 n8n 的问题，还是 API 的问题？
作为一个在自动化泥潭里摸爬滚打多年的老司机，笔者可以负责任地告诉你：90% 的认证错误，都是因为我们忽略了那些不起眼的细节。今天，我就把这些年踩过的坑、填过的雷，一次性分享给大家。
一、坑点一：Basic Auth 到底该怎么填？
很多 API，尤其是老系统，还在使用 Basic Auth（基础认证）。在 n8n 的 HTTP Request 节点中，Auth Type 选择 Basic Auth 后，很多人会直接把用户名和密码填进去，然后运行——报错。
这里有两个大坑：
- 坑位1：用户名/密码的优先级。有时候 API 文档写得不清不楚，它可能只要求填
username，或者只要求填password，甚至要求你把它们拼成特定的格式。 - 坑位2：URL 隐藏参数。有些 API 的认证信息其实是直接挂在 URL 上的，比如
https://user:pass@api.example.com/data。如果你在 Header 里加了 Auth，又在 URL 里带了 Auth，n8n 可能会懵圈。
避坑指南： 在 n8n 中，开启 Basic Auth 时，请务必确保你的 API 文档要求的是标准的 Header 传输模式（即 Authorization: Basic base64(username:password)）。如果 URL 本身包含认证信息，请优先使用 URL 中的格式，并在 n8n 的 Auth 设置中选择 None，不要重复认证。
二、坑点二：Bearer Token 别再手动拼接了
现在更流行的是 OAuth 2.0 或 Bearer Token 认证。很多同学拿到 Token 后，习惯性地在 HTTP Request 节点的 Header 配置里手动添加：Authorization: Bearer xxxxxx。
这虽然能用，但不是最优雅的。一旦 Token 过期，你就得手动去改节点配置。而且，n8n 提供了专门的 Generic Credential Type（通用凭证类型）。
正确姿势：
- 在 n8n 的 Credentials（凭证）管理中，新建一个凭证，选择 Generic Auth。
- 在 Header Name 填入
Authorization，Header Value 填入Bearer {{$credentials.access_token}}（如果是连接 OAuth 流程，n8n 会自动处理）。 - 在 HTTP Request 节点中，直接选中这个凭证即可。
这样做最大的好处是：当 Token 刷新时，你只需要更新凭证，所有使用该凭证的节点都会自动生效，无需一个个去改。
三、坑点三：OAuth 2.0 的回调 URL 深渊
这是 n8n 用户最常遇到的“天坑”，尤其是自托管（Self-hosted）用户。当你配置 OAuth 2.0 凭证时，n8n 会要求你填写 回调 URL (Callback URL)。
如果你使用的是 n8n Cloud，这通常不是问题。但如果你是用 Docker 或源码部署在本地，问题就来了：
- 你的 n8n 运行在
localhost:5678。 - 但 API 服务商（如 Google、GitHub）只能回调到公网 IP。
解决方案：
- 内网穿透（推荐）： 使用
frp、ngrok或Cloudflare Tunnel将你的本地 n8n 映射到公网域名。 - 修改 Callback URL： 在 n8n 的凭证配置中，将 Callback URL 修改为你映射后的公网地址（例如
https://your-domain.com/rest/oauth2-credential/callback）。 - N8N_HOST 配置： 在环境变量中设置
N8N_HOST为你的公网域名，这会自动修正 n8n 生成的回调链接。
笔者经验： 如果你是在本地测试，没有公网 IP，可以使用
n8n start --tunnel启动，n8n 会自动分配一个临时的公网地址，但注意这仅用于测试，生产环境请务必使用稳定的映射方案。
四、坑点四：不仅仅是 401，还有 403 和 429
有时候，认证成功了，但请求依然失败，报错变成了 403 Forbidden 或 429 Too Many Requests。这往往不是认证格式错了，而是权限或频率的问题。
- 403 Forbidden： 说明 Token 是对的，但这个 Token 对应的账号没有操作该资源的权限。比如，你用 Read-only 的 Token 去尝试写入数据。
- 429 Too Many Requests： 说明你触发了 API 的限流策略。n8n 默认的请求速度很快，如果 API 限制每秒 1 次，你瞬间发 10 个请求就会触发 429。
应对策略：
对于 403，回到 API 服务商的控制台，仔细检查 Scopes（权限范围）。对于 429，请在 HTTP Request 节点后添加一个 Wait 节点，或者在 n8n 的 Execution 设置中开启“流控”功能，强制降低执行速度。
五、坑点五：自签名证书的 HTTPS
如果你的 API 运行在内网的 HTTPS 服务上，且使用的是自签名证书（Self-signed Certificate），n8n 默认会因为证书不被信任而拒绝连接，报错通常是 SSL Error 或 UNABLE_TO_VERIFY_LEAF_SIGNATURE。
解决方法：
在 n8n 的 HTTP Request 节点配置中，有一个 Options 选项卡。展开它，找到 Reject Unauthorized（拒绝未经授权的证书），将其设置为 OFF。
警告： 在生产环境中，如果你关闭了证书验证，请务必确保网络环境是安全的，防止中间人攻击。在内网环境（如局域网设备控制）中，这是一个常用的解决方案。
FAQ：关于 n8n API 认证的常见问答
Q1：为什么我在 n8n 里填了凭证，但节点还是提示“找不到凭证”？
A：这通常是因为你创建了凭证，但忘记在具体的 HTTP Request 节点里点击“Select Credential”来关联它。n8n 不会自动绑定凭证，你需要手动在节点配置中选择。
Q2：API 返回的 Token 是 JSON 格式，我该怎么提取出来给后续节点用？
A：使用 Set 节点或 Function 节点。如果你使用 OAuth 2.0 流程，n8n 会自动将 Token 存储在凭证中。如果是手动获取 Token，建议使用 Set 节点，将数据映射到 $credentials 或后续流程可用的变量中。
Q3：如何调试 API 请求，看看到底发了什么？
A：在 HTTP Request 节点中，开启 Full Response 选项，或者在 n8n 的 Executions（执行历史）中查看详细的 Input/Output 数据。你可以看到完整的 Header 和 Body，这对于排查认证错误至关重要。
总结与资源
API 认证看似简单，实则暗藏玄机。在 n8n 中，核心原则是：优先使用凭证（Credentials）管理，而非硬编码；理解 HTTP 状态码的含义；善用调试工具。
如果你在 n8n 的使用过程中遇到了其他棘手的认证问题，欢迎在 N8N大学 的社区留言。记住，每一个报错的 401，都是通往自动化的必经之路。
