飞书文档打开空白的解决方案:

问题现象： 飞书文档打开显示空白，创建时报 400 Bad Request 错误根本原因： Markdown 表格语法不被飞书 Docx API 支持解决方案： 使用 feishu_doc 的 create_table API 创建原生表格解决时间： 2026-03-21

一、问题现象

症状描述

1. 文档打开空白 — 页面能加载，但内容区域什么都没有
2. 创建报 400 错误 — API 返回 400 Bad Request
3. 无法编辑 — 共享文档没有编辑权限

错误内容

| 准则 | 评分 | 分析 |
|------|------|------|
| 简单易懂 | 9/10 ✅ | 商业模式清晰 |
| 经营历史 | 10/10 ✅ | 上市 23 年稳定增长 |

{
  "code": 400,
  "message": "Bad Request"
}

二、根本原因

官方限制说明

Limitation: Markdown tables are NOT supported.

原因解析

为什么容易踩坑

• ✅ Markdown 编辑器都支持表格
• ✅ GitHub、Notion 都能渲染
• ✅ 语法简单直观

三、解决方案

方案一：使用 create_table API（推荐）⭐⭐⭐⭐⭐

# 调用 feishu_doc 的 create_table API
table_data = [
    ["准则", "评分", "分析"],
    ["简单易懂", "9/10 ✅", "商业模式清晰"],
    ["经营历史", "10/10 ✅", "上市 23 年稳定增长"],
    ["长期前景", "9/10 ✅", "品牌护城河极深"]
]

result = feishu_doc.create_table(
    doc_id="I5i2dxu2IoPyHdxEtBccraKJn9d",
    rows=4,
    cols=3,
    data=table_data
)

• ✅ 飞书原生表格块
• ✅ 创建后可直接编辑
• ✅ 支持调整列宽、行高
• ✅ 样式完美，自动对齐
• ✅ 一次 API 调用完成

方案二：HTML 表格（备选）⭐⭐⭐

<table>
  <tr>
    <th>准则</th>
    <th>评分</th>
    <th>分析</th>
  </tr>
  <tr>
    <td>简单易懂</td>
    <td>9/10 ✅</td>
    <td>商业模式清晰</td>
  </tr>
  <tr>
    <td>经营历史</td>
    <td>10/10 ✅</td>
    <td>上市 23 年稳定增长</td>
  </tr>
</table>

• ✅ 飞书 Docx 原生支持
• ✅ 可以保留表格结构

• ⚠️ 语法比 Markdown 复杂
• ⚠️ 手动写比较麻烦

方案三：文本列表（简单场景）⭐⭐⭐

- **简单易懂** — 9/10 ✅ — 商业模式清晰
- **经营历史** — 10/10 ✅ — 上市 23 年稳定增长
- **长期前景** — 9/10 ✅ — 品牌护城河极深

• ✅ 语法最简单
• ✅ 飞书完美支持

• ⚠️ 没有表格的对齐效果
• ⚠️ 不适合复杂数据对比

四、方案对比

1. create_table API（首选）
   ↓
2. HTML 表格（备选）
   ↓
3. 文本列表（简单场景）

五、操作步骤

使用 create_table API 的完整流程

feishu_doc --help

table_data = [
    ["列 1", "列 2", "列 3"],
    ["数据 1", "数据 2", "数据 3"],
    ["数据 4", "数据 5", "数据 6"]
]

result = feishu_doc.create_table(
    doc_id="你的文档 ID",
    rows=3,
    cols=3,
    data=table_data
)

六、常见问题 FAQ

Q1: 为什么飞书不支持 Markdown 表格？

Q2: create_table API 在哪个技能里？

feishu_doc create_table --doc_id <文档 ID> --rows <行数> --cols <列数> --data <数据>

Q3: HTML 表格和 create_table API 有什么区别？

Q4: 创建后可以修改吗？

• 在飞书界面直接编辑
• 用 API 更新单元格内容
• 用 API 调整行列数

Q5: 支持合并单元格吗？

七、核心要点总结

3 个必须记住的点

1. ✅ 飞书 Docx 不支持 Markdown 表格语法 — 这是 API 限制，不是 bug
2. ✅ create_table API 是最佳方案 — 原生表格块，完美支持
3. ✅ HTML 表格和文本列表是备选 — 简单场景可用

推荐方案

首选：create_table API
     ↓
备选：HTML 表格
     ↓
简单场景：文本列表

排查清单

• 查 Skill 文档限制说明
• 确认功能是否原生支持
• 找原生 API 方案
• 备选转换方案
• 测试后再批量使用

八、相关资源

文档链接

• feishu-doc Skill 文档： ~/workspace/skills/feishu-docs/SKILL.md
• 飞书文档 API 官方文档： https://open.feishu.cn/document/ukTMukTMukTM/uEDO0UjLxgDM14SM4gTN
• 飞书多维表格： https://www.feishu.cn/product/bitable

示例文档

• 本文示例文档： https://www.feishu.cn/docx/I5i2dxu2IoPyHdxEtBccraKJn9d
• 解决方案详解： https://www.feishu.cn/docx/ODmBd4b5VoImgSxTAPZcullsn8g

九、经验总结

踩坑成本

• 排查时间： 约 5 小时
• 无效尝试： AI 诊断、权限检查、缓存清理、多端测试
• 根本原因： 没有先查 Skill 文档的限制说明

关键收获

1. 遇到 API 错误先查文档限制说明
2. 原生 API 比转换方案可靠
3. 不要假设”应该支持”，要确认”确实支持”

正确排查路径

1. 查 Skill 文档限制说明（30 分钟）
   ↓
2. 确认功能是否支持
   ↓
3. 找原生 API 方案
   ↓
4. 测试后批量使用