n8n 能不能接入飞书？

[pls (评论尸)]

常见问题，预制一下。

[AIBot-n8n (AI答疑-n8n)]

很多社区的朋友都在问：n8n 能不能接入飞书的各项功能？答案是：能，而且非常灵活！

虽然 n8n 核心库目前没有 直接命名为 “飞书” 的官方节点，但这并不妨碍我们集成。本文将作为一篇详细的教程贴，带你一步步探索 n8n 连接飞书的各种方法，从社区节点到强大的 HTTP Request 节点，让你能够根据自己的需求，选择最合适的方式，解锁 n8n 与飞书集成的无限可能。

n8n 与飞书集成的现状

在开始动手之前，我们先了解一下当前 n8n 连接飞书的几种主要途径：

1. 官方/内置节点情况 (Official/Built-in Nodes):

• 目前，n8n 的标准发行版中，并没有提供专门针对飞书（Feishu）的官方集成节点 1。
• 不过，在一些特定的 n8n 文档源或版本中（例如 docs-tech.n8n.vn），提到了名为 Lark Base 3、Lark Messenger 4、Lark Custom Bot 3 和 Lark AI 3 的节点。这些节点提供了对 Lark/飞书部分功能（如多维表格、消息发送）的封装。需要注意的是，这些节点的可用性可能取决于你使用的 n8n 版本或来源，它们并非 n8n 官方文档 docs.n8n.io 中列出的标准内置节点。社区中也有对官方 LarkSuite 节点的需求讨论 5。

2. 社区节点 (Community Nodes):

• n8n 拥有活跃的社区，开发者可以创建和分享自定义节点 6。
• 社区中存在一个名为 n8n-nodes-feishu-lite 的飞书节点，由社区成员开发 8。
• 功能覆盖: 这个节点提供了一些常用功能，包括：
  • 通讯录 (Address Book): 搜索用户、获取用户信息、通过手机号/邮箱获取用户 ID 等 8。
  • 电子表格 (Spreadsheet): 创建/获取/修改表格和工作表、读写数据、操作行列、单元格样式设置等 8。
  • 消息 (Message): 发送/回复/撤回/编辑/转发消息、批量发送/撤回消息等 8。
• 优势: 对于节点已支持的功能，使用社区节点可以简化配置过程。
• 注意事项: 社区节点的维护状态和可靠性需要自行评估。虽然开发者表示会持续开发 8，但其更新频率和问题修复可能不如官方节点及时。使用前建议查看其 npm 页面 8 或在社区论坛 8 了解最新动态。

3. HTTP Request 节点:

• 这是 最通用、最强大 的方法，也是本文重点介绍的方式。
• n8n 的(HTTP Request node documentation | n8n Docs) 10 允许你直接调用任何提供 API 的服务，包括飞书开放平台提供的丰富 API 1。
• 优势: 可以接入飞书开放平台 所有 开放的 API 功能，不受限于特定节点的封装，灵活性极高。
• 挑战: 相较于专用节点，需要对飞书 API 的调用方式（URL、方法、认证、参数）有一定了解 13。

结论: 对于简单、已覆盖的需求，可以尝试 n8n-nodes-feishu-lite 社区节点。但要实现全面、灵活、可靠的飞书集成，掌握 HTTP Request 节点 是必备技能。

准备工作：飞书开放平台设置

无论使用哪种方法（特别是 HTTP Request 节点），你都需要在飞书开放平台进行一些基础设置。

1. 创建应用 (Create App):

• 访问 飞书开放平台 (https://open.feishu.cn/) 或国际版 Lark Open Platform (https://open.larkoffice.com/) 11。
• 登录你的飞书账号，进入“开发者后台”。
• 根据你的需求，通常选择创建“企业自建应用”（Custom App）13。如果你是 ISV 开发者，也可以创建“商店应用”（Store App）13。
• 按照指引填写应用名称、描述等信息。

2. 获取凭证 (Get Credentials):

• 应用创建成功后，进入应用详情页。
• 在“凭证与基础信息”（Credentials & Basic Info）页面，找到并妥善保管你的 App ID 和 App Secret 13。这是你的应用身份标识，调用 API 时会用到。切记不要泄露 App Secret！

3. 配置权限 (Configure Permissions):

• 这是非常关键的一步。你需要根据你希望 n8n 实现的功能，为应用申请对应的 API 权限（Scope）13。
• 在应用详情页的“开发配置” > “权限管理”页面操作 15。
• 例如：
  • 发送消息需要 im:message:create 等权限 17。
  • 读取通讯录信息可能需要 contact:user.readonly 等权限 18。
  • 操作多维表格需要 bitable:app:readonly, bitable:app:readwrite 等权限 19。
  • 处理审批需要 approval:approval:read, approval:instance:readwrite 等权限 20。
• 飞书的权限分为“免审权限”（申请后立即生效）和“需管理员审核权限” 15。对于企业自建应用，部分权限需要企业管理员审核通过后才能生效 15。
• 某些 API（如通讯录、飞书人事）可能还需要配置“数据权限”，以限定应用能访问的数据范围 13。
• 建议: 遵循最小权限原则，只申请必要权限。

4. (可选) 配置 IP 白名单 (IP Whitelist):

• 为了提高安全性，可以在“安全设置”中配置 IP 白名单 13。只有来自白名单 IP 地址的 API 请求才会被飞书服务器接受。如果你的 n8n 实例有固定的公网 IP，建议配置此项。

核心方法：使用 HTTP Request 节点连接飞书

这是实现飞书集成的最核心、最灵活的方式。

认证流程与凭证管理

飞书 API 主要通过 access_token 进行认证 13。常用的有两种：

• tenant_access_token: 应用级别的凭证，代表应用自身进行操作。适用于大部分机器人、自动化场景（如发送群消息、操作应用拥有的多维表格等）。需要使用 App ID 和 App Secret 获取 14。
• user_access_token: 用户级别的凭证，代表某个具体用户进行操作。适用于需要模拟用户行为的场景（如操作用户个人日历、以用户身份发送邮件等）。获取流程遵循标准的 OAuth 2.0，相对复杂，需要用户授权 16。

对于常见的自动化任务，我们主要使用 tenant_access_token。关键点在于，tenant_access_token 有效期通常为 2 小时，需要在使用前获取或刷新。

在 n8n 中安全、动态地处理 tenant_access_token:

直接将 App ID 和 App Secret 填入 n8n 的凭证管理（Credentials）中用于获取 tenant_access_token 是不推荐的，因为 tenant_access_token 会过期。推荐使用以下模式：

1. 步骤 1: 获取 Token 节点

• 在 n8n 工作流的开始部分，添加一个 HTTP Request 节点，专门用于获取 tenant_access_token。
• Method: POST
• URL: https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal/ (国内) 或相应的 Lark 地址。
• Body Content Type: JSON
• Body Parameters:
  • app_id: 填入你的 App ID
  • app_secret: 填入你的 App Secret
• 给这个节点命名，例如 “Get Feishu Token”。

2. 步骤 2: 使用 Token 的节点

• 在后续需要调用飞书 API 的 HTTP Request 节点中，配置认证头。
• Authentication: 选择 Header Auth。
• Name: Authorization
• Value: 使用 n8n 的表达式动态引用上一步获取的 Token。点击 Value 旁边的齿轮图标，选择 “Add Expression”，输入类似：Bearer {{ $node.json.tenant_access_token }} 25。
• 这样，每次工作流运行时，都会先获取最新的 tenant_access_token，然后后续节点使用这个最新的 Token 进行 API 调用，避免了 Token 过期问题，也无需将 App Secret 暴露在每个节点的配置中。

构建 API 请求

配置好认证后，调用具体的飞书 API 就很简单了：

• 查阅文档: 首先，你需要查阅 飞书开放平台 API 文档 12 (或 Lark 文档 11)，找到你需要的功能对应的 API 接口说明。文档会告诉你 API 的：
  • HTTP Method: GET, POST, PUT, DELETE 等 13。
  • Request URL: 接口的访问地址 13。
  • Query Parameters: URL 中 ? 后面的参数 14。
  • Request Header: 除了 Authorization，通常还需要 Content-Type: application/json; charset=utf-8 14。
  • Request Body: POST 或 PUT 请求通常需要发送 JSON 格式的数据 14。
  • 所需权限 (Scopes): 确保你的飞书应用已申请这些权限 15。
• 使用 API Explorer: 飞书提供了 API Explorer (API 调试台) 28，这是一个非常方便的工具。你可以在这里选择 API、填写参数、自动获取测试 Token 并直接发起调用，查看请求和响应。它还能生成多种语言（包括 cURL）的示例代码，你可以参考 cURL 示例来配置 n8n 的 HTTP Request 节点 17。
• 配置 n8n 节点:
  • 在 n8n 中添加 HTTP Request 节点。
  • 设置 Method 和 URL。
  • 在 Authentication 中选择 Header Auth 并配置动态 Authorization (如上一节所述)。
  • 在 Options > Header 中添加 Content-Type 为 application/json; charset=utf-8。
  • 如果 API 需要 Query Parameters，在 Options > Query 中添加。
  • 如果 API 需要 Request Body，选择 Body Content Type 为 JSON，并在 Body Parameters 中添加 JSON 键值对。你可以使用表达式动态传入来自前面节点的数据。

实战演练：常见飞书功能接入示例

下面我们通过几个实例，演示如何使用 HTTP Request 节点接入飞书的关键功能。

示例 1：发送文本消息到飞书群聊

假设我们要向指定的飞书群发送一条文本消息。

1. 飞书 API:

• Endpoint: POST /open-apis/im/v1/messages 17
• Query Parameter: receive_id_type=chat_id (表示接收者是群聊) 17
• Headers: Authorization: Bearer <tenant_access_token>, Content-Type: application/json; charset=utf-8 17
• Request Body (JSON): 17 JSON{ "receive_id": "oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // 目标群聊的 Chat ID "msg_type": "text", "content": "{\"text\":\"来自 n8n 的问候！ Hello from n8n!\"}" // 注意 content 是 JSON 字符串 }
• 所需权限: im:message:create

2. n8n Workflow:

• Node 1: Start (手动触发或根据你的场景选择其他触发器)
• Node 2: Set (配置消息)
  • 设置 chat_id (字符串): oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx (替换为你的目标群聊 ID)
  • 设置 message_text (字符串): 来自 n8n 的问候！ Hello from n8n!
• Node 3: Get Feishu Token (如上文“认证流程”所述配置)
• Node 4: Send Feishu Message (HTTP Request)
  • Method: POST
  • URL: https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id (注意 Query Parameter)
  • Authentication: Header Auth, Name: Authorization, Value (Expression): Bearer {{ $node.json.tenant_access_token }}
  • Send Body: On
  • Body Content Type: JSON
  • Body Parameters: (点击 “Add Parameter”)
    • Key: receive_id, Value (Expression): {{ $node.json.chat_id }}
    • Key: msg_type, Value: text
    • Key: content, Value (Expression): {{ JSON.stringify({ text: $node.json.message_text }) }} (注意这里用 JSON.stringify 将文本包装成 JSON 字符串)运行这个工作流，你应该就能在指定的飞书群里看到来自 n8n 的消息了！发送卡片消息: 如果想发送更丰富的卡片消息 (msg_type: "interactive")，content 字段需要传入卡片的 JSON 结构字符串。你可以使用 飞书卡片搭建工具 4 设计卡片，然后将生成的 JSON 填入 content。例如：JSON// content 的值 (需要是字符串) "{\"config\":{\"wide_screen_mode\":true},\"header\":{\"title\":{\"tag\":\"plain_text\",\"content\":\"n8n 提醒\"},\"template\":\"blue\"},\"elements\":[{\"tag\":\"div\",\"text\":{\"tag\":\"lark_md\",\"content\":\"**订单号:** {{ $json.orderId }}\\n**状态:** 已发货\"}}]}"在 n8n 中，你需要动态替换 {{ $json.orderId }} 等占位符，可以使用字符串替换或模板引擎。

示例 2：操作飞书多维表格 (Bitable / Base)

飞书多维表格是非常强大的数据管理工具。

• 使用 Lark Base 节点 (如果可用): 如果你使用的 n8n 版本包含 Lark Base 节点 3，这是最简单的方式。
  • 配置凭证: 在 n8n 的 Credentials 中添加 Lark 凭证，填入 App ID 和 App Secret 3。
  • 使用节点: 添加 Lark Base 节点，选择操作（如 List Records, Create Record, Update Record 等），填入 App Token (多维表格的唯一标识) 和 Table ID，然后配置字段映射 3。
• 使用 HTTP Request 节点:
  • 获取 App Token 和 Table ID: 在飞书多维表格的 URL 或分享设置中可以找到。
  • 查阅 API: 查阅 多维表格 API 文档 19。常用 API 包括：
    • GET /open-apis/bitable/v1/apps/:app_token/tables/:table_id/records (列出记录)
    • POST /open-apis/bitable/v1/apps/:app_token/tables/:table_id/records (创建记录)
    • PUT /open-apis/bitable/v1/apps/:app_token/tables/:table_id/records/:record_id (更新记录)
    • DELETE /open-apis/bitable/v1/apps/:app_token/tables/:table_id/records/:record_id (删除记录)
  • n8n Workflow (以创建记录为例):
    • Node 1: Start
    • Node 2: Set (配置数据)
      • app_token: “bascnxxxxxxxxxxxx”
      • table_id: “tblxxxxxxxxxxxx”
      • record_data (JSON): { "fields": { "字段名1": "值1", "字段名2": 123 } } (字段名需与多维表格中的一致)
    • Node 3: Get Feishu Token
    • Node 4: Create Bitable Record (HTTP Request)
      • Method: POST
      • URL (Expression): https://open.feishu.cn/open-apis/bitable/v1/apps/{{ $node.json.app_token }}/tables/{{ $node.json.table_id }}/records
      • Authentication: Header Auth (配置同上)
      • Send Body: On
      • Body Content Type: JSON
      • Body Parameters (Expression): {{ $node.json.record_data }}

示例 3：接收飞书事件 (Webhook 触发 n8n)

让飞书事件（如收到新消息、审批状态变更）触发 n8n 工作流，实现更实时的自动化。

1. 飞书开放平台设置:

• 进入应用的“开发配置” > “事件订阅” 31。
• 订阅方式: 选择“通过 Webhook 推送事件给开发者服务器”（Send notifications to developer’s server）21。
• 请求地址 URL (Request URL): 填入 n8n 的 Webhook 节点提供的 URL (后面会讲如何获取)。飞书会向此 URL 发送一个验证请求，确保你的 n8n 服务能正常接收 32。
• (推荐) 安全设置: 在“加密策略”中，配置 Encrypt Key 和 Verification Token 21。Encrypt Key 用于加密事件内容，Verification Token 用于验证请求来源。n8n 的 Webhook 节点目前不直接支持自动解密和验证 Token，你可能需要在工作流中添加代码节点来处理（或暂时不启用加密，仅依赖 URL 的唯一性）。
• 添加事件: 点击“添加事件”，选择你需要订阅的事件，例如：
  • im.message.receive_v1 (接收消息) 32
  • approval.instance.update_v4 (审批实例状态变更) 20
  • contact.user.created_v3 (用户创建) 32
  • im.chat.member.user.added_v1 (用户加入群聊) 37
• 确保为所选事件申请了必要的权限 32。
• 发布版本: 修改事件订阅配置后，需要创建并发布一个新的应用版本才能生效 38。

2. n8n Workflow 设置:

• Node 1: Webhook Trigger
  • 添加 Webhook 节点 6。
  • Authentication: 通常选择 None (如果飞书端未配置特殊认证)。
  • HTTP Method: POST。
  • Path: 节点会自动生成一个唯一的路径。
  • Response Mode: 选择 On Received。飞书要求在 3 秒内响应 HTTP 200 33，所以要尽快响应。
  • Webhook URLs: 节点会显示 Test URL 和 Production URL。将 Production URL 复制并粘贴到飞书开放平台的“请求地址 URL”中 32。
  • 测试: 点击 “Listen For Test Event”。然后在飞书里触发你订阅的事件（例如，给机器人发消息），n8n 应该能接收到数据。飞书首次配置 URL 时也会发送一个 url_verification 类型的事件，你需要让 n8n 接收这个事件并返回包含 challenge 字段的 JSON 响应，才能验证 URL 成功。
• 后续节点: Webhook 节点会将接收到的飞书事件数据（JSON 格式）作为输出 21。你可以根据 event.header.event_type 等字段判断事件类型，并进行相应的处理，例如：
  • 如果是消息事件，提取消息内容、发送者、群聊 ID。
  • 如果是审批事件，提取实例 ID、状态、审批人等。注意: 飞书可能会重发事件，你需要根据事件数据中的 event_id (v2.0 事件) 或 uuid (v1.0 事件) 进行幂等处理，避免重复执行工作流 33。

示例 4：(进阶) 处理审批流程

通过 API 与飞书审批进行交互是比较复杂但非常有价值的场景。

1. 创建审批实例:

• API: POST /open-apis/approval/v4/instances 39
• 关键参数: 39
  • approval_code: 审批定义的唯一编码。你需要先在飞书后台创建好审批流程，并在开发者模式下获取其 Code 20。
  • user_id 或 open_id: 发起人的 ID。
  • form: JSON 字符串，包含审批表单中各控件的值。其结构需要与审批定义的表单结构完全匹配 20。
  • (可选) node_approver_user_id_list: 如果流程中有“发起人自选”的审批节点，可以在这里指定审批人。
• n8n 实现: 类似发送消息，使用 HTTP Request 节点，配置好 URL、认证和 Body Parameters。form 参数通常需要根据前面的节点动态构建 JSON 字符串。

2. 获取审批结果/状态更新:

• 最佳方式: 订阅审批相关的事件，如 approval.instance.update_v4 20。当审批状态（通过、拒绝、转交等）发生变化时，飞书会通过 Webhook 通知 n8n。
• 主动查询: 也可以调用 GET /open-apis/approval/v4/instances/:instance_code API 来查询特定审批实例的详情和状态 20。

3. 执行审批操作 (Approve/Reject - 较少见):

• 飞书审批的核心逻辑通常在飞书内部完成。虽然理论上可能存在 API (/approval/v4/instance/approve, /approval/v4/instance/reject 等，具体需查阅最新文档) 允许通过 API 进行审批操作，但这通常用于与第三方系统集成（外部审批同步）42。对于标准的企业自建应用，审批操作一般由用户在飞书客户端完成。

4. 评论与抄送:

• API POST /open-apis/approval/v4/instances/:instance_code/comments 可以添加评论 20。
• API POST /open-apis/approval/v4/instances/:instance_code/cc 可以添加抄送人 20。

注意事项与最佳实践

在 n8n 与飞书集成的过程中，有几点需要特别注意：

• 社区节点维护性: 如果你选择使用社区节点（如 n8n-nodes-feishu-lite），请关注其更新情况和社区反馈 8。社区节点可能无法及时跟进飞书 API 的更新，或存在未修复的 Bug。依赖社区节点意味着需要承担一定的维护风险。
• 错误处理: API 调用并非总能成功。
  • 飞书 API 错误: 飞书 API 会返回错误码 (code) 和错误信息 (msg) 14。在 n8n 工作流中，你需要检查 HTTP Request 节点的输出，判断是否出错，并根据错误信息进行处理（例如，记录日志、发送通知、重试）。
  • n8n 错误处理: 利用 n8n 节点的 “Settings” > “Error Handling” 选项 6。可以设置 “Retry On Fail” 来自动重试失败的 API 请求，或者设置 “Continue (using error output)” 并连接到错误处理分支。也可以使用全局的 Error Trigger Workflow 来捕获和处理失败的执行。
• API 变更风险: 飞书开放平台会不断迭代更新。如果你使用 HTTP Request 节点直接调用 API，需要留意飞书的 API 变更通知。某些变更可能导致你现有的工作流失效，需要及时调整。
• 安全第一:
  • 凭证安全: 绝对不要 将 App Secret 或动态获取的 access_token 硬编码在工作流的 JSON 中或暴露在执行日志里。遵循上文提到的动态获取 Token 模式 25。
  • IP 白名单: 如果条件允许，为你的飞书应用配置 IP 白名单，只允许来自 n8n 服务器 IP 的请求 13。
  • Webhook 安全: 如果使用 Webhook 接收飞书事件，务必使用 HTTPS。推荐在飞书端配置 Encrypt Key 和 Verification Token，并在 n8n 端进行相应的解密和验证（可能需要 Code 节点实现），以确保数据安全和请求来源可靠 21。

总结与资源

通过本教程，我们了解到 n8n 连接飞书（Lark）主要有两种方式：

1. 社区节点 (n8n-nodes-feishu-lite): 适用于该节点已支持的功能，配置相对简单，但需关注其维护性和可靠性。
2. HTTP Request 节点: 最强大、最灵活的方式，可以调用飞书开放平台的 所有 API，实现完全自定义的集成，是实现复杂、可靠集成的推荐方案。

掌握了 HTTP Request 节点的使用方法，配合飞书开放平台的文档，你可以构建出各种强大的自动化工作流，例如：

• 将 CRM 系统的新客户信息同步到飞书群。
• 根据监控告警自动发送消息到运维群。
• 将表单提交的数据自动写入飞书多维表格。
• 当飞书审批通过后，自动触发后续系统的操作。
• … 无限可能！

重要资源链接:

• n8n 官方文档: https://docs.n8n.io/ 1
• n8n 社区论坛: https://community.n8n.io/ 45
• 飞书开放平台 (国内版): 开发文档 - 飞书开放平台 12
• Lark Open Platform (国际版): 开发文档 - 飞书开放平台 11
• 飞书 API Explorer (API 调试台): 开发文档 - 飞书开放平台 28
• n8n-nodes-feishu-lite 社区帖子: Custom: Feishu (飞书) Node - Built with n8n - n8n Community 8
• n8n HTTP Request 节点文档: HTTP Request node documentation | n8n Docs 10

祝大家自动化愉快！