feishu-bitable

n8n community node for Feishu/Lark Bitable - Read, write and manage Feishu Bitable data with simple text filter syntax

Package Information

Downloads: 55 weekly / 131 monthly

Latest Version: 0.1.0

Author: loobayn

Available Nodes

Feishu Bitable

读取、写入和管理飞书多维表格数据，支持简单的文本语法筛选

Documentation

n8n-nodes-feishu-bitable

n8n 飞书多维表格节点 - 读取、写入和管理飞书多维表格数据，支持简单的文本语法筛选。

功能特性

操作类型	功能说明	适用场景
读取记录	从飞书多维表格获取数据	数据同步、报表生成、数据分析
写入记录	向飞书多维表格写入文本数据	数据更新、批量导入、状态变更
上传附件	上传文件到附件字段	图片存储、文档归档、资源管理

安装说明

方式一：通过 n8n 社区节点安装（推荐）

步骤	操作位置	具体操作
1	n8n 主界面	点击左下角 Settings 图标
2	Settings 页面	选择左侧菜单 Community Nodes
3	Community Nodes 页面	点击 Install a community node 按钮
4	安装对话框	输入 `n8n-nodes-feishu-bitable`
5	安装对话框	点击 Install 按钮
6	等待安装完成	安装成功后节点会出现在节点列表中

方式二：手动安装（Docker 环境）

# 进入 n8n 自定义节点目录
cd ~/.n8n/custom

# 使用 npm 安装
npm install n8n-nodes-feishu-bitable

# 重启 n8n 服务
docker restart n8n

方式三：本地开发安装

# 克隆仓库
git clone https://github.com/your-repo/n8n-nodes-feishu-bitable.git

# 进入项目目录
cd n8n-nodes-feishu-bitable

# 安装依赖
npm install

# 构建项目
npm run build

# 链接到 n8n
npm link

# 在 n8n 自定义节点目录中链接
cd ~/.n8n/custom
npm link n8n-nodes-feishu-bitable

凭证配置

步骤 1：创建飞书应用

步骤	操作位置	具体操作
1	浏览器	访问飞书开放平台
2	开放平台首页	点击右上角登录并完成登录
3	开发者后台	点击创建企业自建应用
4	创建应用页面	填写应用名称（如：n8n 数据同步）
5	创建应用页面	填写应用描述
6	创建应用页面	点击创建按钮

步骤 2：获取应用凭证

字段名	获取位置	说明
App ID	应用详情 → 凭证与基础信息	格式如 `cli_xxxxxxxxxx`
App Secret	应用详情 → 凭证与基础信息	点击"显示"查看，格式为 32 位字符串

步骤 3：配置应用权限

在飞书开放平台的应用详情页，进入 权限管理 → API 权限，开启以下权限：

权限名称	权限标识	用途
查看、评论、编辑和管理多维表格	`bitable:app`	读取和写入表格数据
上传、下载文件	`drive:drive`	上传附件文件

步骤 4：在 n8n 中配置凭证

步骤	操作位置	具体操作
1	n8n 主界面	点击左侧 Credentials
2	Credentials 页面	点击 Add Credential
3	选择凭证类型	搜索并选择 Feishu Bitable API
4	凭证配置页面	填写 App ID
5	凭证配置页面	填写 App Secret
6	凭证配置页面	点击 Save 保存

节点配置说明

通用字段

字段名	类型	必填	说明
凭证	下拉选择	✅	选择已配置的 Feishu Bitable API 凭证
操作类型	下拉选择	✅	选择：读取记录 / 写入记录 / 上传附件
表格链接	文本	✅	粘贴飞书多维表格的完整链接

表格链接格式

支持以下链接格式：

# 标准格式
https://xxx.feishu.cn/base/{app_token}?table={table_id}

# 带视图参数（视图参数会被忽略）
https://xxx.feishu.cn/base/{app_token}?table={table_id}&view={view_id}

# 示例
https://example.feishu.cn/base/bascnXXXXXXXXXX?table=tblXXXXXXXXXX

读取记录操作

字段名	类型	必填	说明
输出列	多行文本	❌	每行一个列名，留空返回所有列
筛选条件	多行文本	❌	每行一条筛选规则，语法见下文
最大行数	数字	❌	限制返回的最大记录数，默认无限制

写入记录操作

字段名	类型	必填	说明
目标列	文本	✅	要写入数据的列名
写入内容	文本	✅	要写入的内容，支持表达式
筛选条件	多行文本	❌	筛选要更新的记录
新增行	开关	❌	开启后创建新记录而非更新
新增行数	数字	❌	新增行模式下要创建的行数（1-100）

上传附件操作

字段名	类型	必填	说明
目标列	文本	✅	附件字段的列名
二进制属性	文本	✅	包含文件数据的二进制属性名
筛选条件	多行文本	❌	筛选要添加附件的记录
新增行	开关	❌	开启后创建新记录并添加附件

筛选条件语法

本节点支持简单的文本语法来筛选表格记录，无需编写复杂的 JSON 配置。

基本语法

语法格式	功能说明	示例
`列名+关键词`	仅包含该列包含关键词的行	`状态+进行中`
`列名-关键词`	排除该列包含关键词的行	`状态-已完成`
`列名+空值`	仅包含该列为空的行	`备注+空值`
`列名-空值`	排除该列为空的行	`备注-空值`
`列名+非空值`	仅包含该列非空的行	`备注+非空值`
`列名-非空值`	排除该列非空的行	`备注-非空值`

多条件组合规则

条件类型	组合逻辑	说明
包含条件（+）	AND	记录必须同时满足所有包含条件
排除条件（-）	OR	记录只要满足任一排除条件就会被排除

匹配规则

规则	说明
大小写不敏感	`状态+进行中` 会匹配 "进行中"、"JINXINGZHONG" 等
包含匹配	`标题+报告` 会匹配 "月度报告"、"报告总结" 等
列表字段	对于多选字段，任一选项匹配即可

筛选示例

# 示例 1：筛选状态为"进行中"且优先级为"高"的记录
状态+进行中
优先级+高

# 示例 2：筛选有负责人的记录
负责人+非空值

# 示例 3：排除已完成和已取消的记录
状态-已完成
状态-已取消

# 示例 4：筛选标题包含"报告"且备注不为空的记录
标题+报告
备注-空值

使用示例

示例 1：读取表格数据

场景：从飞书多维表格读取所有"进行中"的任务

节点配置：

字段	值
操作类型	读取记录
表格链接	`https://example.feishu.cn/base/bascnXXX?table=tblXXX`
输出列	`标题` `状态` `负责人` `截止日期`
筛选条件	`状态+进行中`

示例 2：更新记录状态

场景：将所有"待处理"的任务状态更新为"进行中"

节点配置：

字段	值
操作类型	写入记录
表格链接	`https://example.feishu.cn/base/bascnXXX?table=tblXXX`
目标列	`状态`
写入内容	`进行中`
筛选条件	`状态+待处理`

示例 3：批量新增记录

场景：批量创建 5 条新任务记录

节点配置：

字段	值
操作类型	写入记录
表格链接	`https://example.feishu.cn/base/bascnXXX?table=tblXXX`
目标列	`标题`
写入内容	`{{ $json.taskName }}`
新增行	✅ 开启
新增行数	`5`

示例 4：上传图片附件

场景：将工作流中的图片上传到表格的附件字段

节点配置：

字段	值
操作类型	上传附件
表格链接	`https://example.feishu.cn/base/bascnXXX?table=tblXXX`
目标列	`附件`
二进制属性	`data`
筛选条件	`任务ID+{{ $json.taskId }}`

输出格式

读取操作输出

{
  "records": [
    {
      "record_id": "recXXXXXXXX",
      "标题": "任务标题",
      "状态": "进行中",
      "负责人": [
        {
          "id": "ou_xxxxx",
          "name": "张三"
        }
      ],
      "截止日期": 1703980800000,
      "备注": null
    }
  ],
  "status": "success",
  "affectedCount": 1,
  "message": "成功读取 1 条记录"
}

写入操作输出

{
  "status": "success",
  "affectedCount": 5,
  "message": "成功更新 5 条记录"
}

附件上传输出

{
  "status": "success",
  "affectedCount": 1,
  "message": "成功上传附件到 1 条记录",
  "fileToken": "boxcnXXXXXXXX"
}

测试验证

验证凭证配置

在 n8n 凭证配置页面点击 Test 按钮，预期结果：

结果	说明
✅ Connection tested successfully	凭证配置正确
❌ Invalid credentials	App ID 或 App Secret 错误

验证节点功能

创建一个简单的工作流
添加 Manual Trigger 节点
添加 Feishu Bitable 节点
配置读取操作，不设置筛选条件
执行工作流，检查是否能获取到表格数据

验证检查项

检查项	预期结果
节点出现在节点列表	搜索"飞书"或"Feishu"可找到
凭证测试通过	显示连接成功
读取操作正常	返回表格记录数据
筛选条件生效	返回符合条件的记录
写入操作正常	表格数据被更新

问题排查

问题现象	检查项	解决方法
凭证测试失败	App ID 和 App Secret 是否正确	重新从飞书开放平台复制凭证
无法访问表格	应用是否有表格权限	在飞书开放平台开启 `bitable:app` 权限
无法访问表格	表格是否授权给应用	在表格设置中添加应用为协作者
链接解析失败	链接格式是否正确	确保链接包含 `base/` 和 `table=`
筛选无结果	列名是否正确	检查列名是否与表格中完全一致
筛选无结果	关键词是否存在	检查表格中是否有匹配的数据
写入失败	目标列是否存在	检查列名是否正确
写入失败	字段类型是否匹配	确保写入内容与字段类型兼容
附件上传失败	是否有云盘权限	开启 `drive:drive` 权限
附件上传失败	目标列是否为附件类型	确保目标列是附件字段
请求超时	网络是否正常	检查网络连接，稍后重试
请求过于频繁	是否触发限流	等待一段时间后重试

配置清单

飞书开放平台配置

配置项	位置	值
应用类型	创建应用时选择	企业自建应用
API 权限 - 多维表格	权限管理 → API 权限	`bitable:app`
API 权限 - 云盘	权限管理 → API 权限	`drive:drive`

n8n 凭证配置

字段	来源	格式
App ID	飞书开放平台 → 应用详情 → 凭证与基础信息	`cli_xxxxxxxxxx`
App Secret	飞书开放平台 → 应用详情 → 凭证与基础信息	32 位字符串

表格授权配置

配置项	位置	操作
添加应用为协作者	表格右上角 → 分享 → 添加协作者	搜索并添加应用
设置权限级别	添加协作者时选择	选择"可编辑"或"可管理"

开发指南

环境要求

依赖	版本要求
Node.js	>= 18.10
npm	>= 9.0

开发命令

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建项目
npm run build

# 运行测试
npm test

# 运行测试（监听模式）
npm run test:watch

# 代码检查
npm run lint

# 代码格式化
npm run format

项目结构

n8n-nodes-feishu-bitable/
├── credentials/
│   └── FeishuBitableApi.credentials.ts  # 凭证定义
├── nodes/
│   └── FeishuBitable/
│       ├── FeishuBitable.node.ts        # 节点主体
│       ├── FeishuApiClient.ts           # API 客户端
│       ├── FilterParser.ts              # 筛选条件解析器
│       ├── UrlParser.ts                 # 链接解析器
│       └── feishu.svg                   # 节点图标
├── dist/                                # 构建输出
├── package.json
├── tsconfig.json
└── README.md

许可证

MIT License

feishu-bitableInstall

Package Information

Available Nodes

Documentation

n8n-nodes-feishu-bitable

功能特性

安装说明

方式一：通过 n8n 社区节点安装（推荐）

方式二：手动安装（Docker 环境）

方式三：本地开发安装

凭证配置

步骤 1：创建飞书应用

步骤 2：获取应用凭证

步骤 3：配置应用权限

步骤 4：在 n8n 中配置凭证

节点配置说明

通用字段

表格链接格式

读取记录操作

写入记录操作

上传附件操作

筛选条件语法

基本语法

多条件组合规则

匹配规则

筛选示例

使用示例

示例 1：读取表格数据

示例 2：更新记录状态

示例 3：批量新增记录

示例 4：上传图片附件

输出格式

读取操作输出

写入操作输出

附件上传输出

测试验证

验证凭证配置

验证节点功能

验证检查项

问题排查

配置清单

飞书开放平台配置

n8n 凭证配置

表格授权配置

开发指南

环境要求

开发命令

项目结构

许可证

相关链接

Discussion

feishu-bitable