Notion 数据库 Files & media(文件与媒体)属性与 API 原生文件直传深度实战:从画廊封面裁切、File Upload API 三步入库到 Formula 2.0 交付物缺失与外链合规门禁闭环

2026 年 11 月 20 日

一、为什么“附件随便往页面或 Files & media 里拖”会引发资产失控? #

在搭建合同归档库、设计素材库、客户交付台账或研发文档中心时,许多团队都会顺手添加一列 Files & media(文件与媒体) 属性来存放 PDF 合同、设计稿图片或压缩包(基础属性用法参阅 Notion 数据库属性官方指南 与 上传文件指南)。

但随着业务记录增长到数千条,缺乏结构治理的媒体附件很快会暴露三类工程痛点:

  1. 画廊封面空白与缩略图错位:在 Gallery(画廊)视图中把 Card preview 绑定到 交付附件 后,发现大量卡片封面一片空白——原因在于同一单元格内混传了 ZIP、Word 与图片,系统默认只抓取排在第一位的媒体文件作为封面;
  2. 外部链接与内部直传混杂,迁移导出时批量丢失:部分成员在 Files & media 中贴入了第三方网盘或图床 Embed link,而另一部分成员直接上传了本地文件;当执行 Export as CSV 归档时,才发现原生上传文件只导出带有效期的签名链接,外链则直接依赖外部站点存活;
  3. 交付物缺少强约束,空文件也可流转结单:工单或项目已经切到 已完成 状态,但 交付附件 单元格依然为空,或只传了一个未定稿的截图,缺少自动校验与拦截机制。

在规划企业级数字资产台账前,先厘清 Notion 中四种常见文件挂载方式的架构边界:

对比维度 数据库 Files & media 属性 页面正文块(/file / /image) 纯 URL 链接属性 Notion File Upload API(/v1/file_uploads)
Gallery 卡片封面调用 原生支持(直接设为 Card preview 数据源) 仅能由 Page cover 或正文第一张图被动提取 不支持渲染卡片预览图 绑定到 Files & media 后与手动上传完全一致
Formula 2.0 可检测性 可直接读取数量、判空与匹配域名/后缀 完全不可被 Formula 公式读取 可直接正则校验协议与域名 绑定入库后可直接纳入 Formula 2.0 巡检
单格多文件与排序能力 支持单格挂载多文件并拖动 ⋮⋮ 排序 按正文 Block 顺序纵向或分栏排列 仅能存储单一目标链接 支持通过数组按序写入多个 file_upload 对象
API 读取与签名有效期 原生上传返回临时 S3 签名(约 1 小时失效) 原生上传返回临时 S3 签名(约 1 小时失效) 原样返回静态外部 URL 上传后由 Notion 托管,读取同样走临时 S3 签名
典型最优适用场景 合同 PDF、发票凭证、主视觉封面、交付包 长篇图解说明、穿插在章节内的操作截图 超大视频、企业网盘共享目录、永久图床直链 ERP/CRM 自动化归档发票、CI 产物自动入库

二、Files & media 属性核心实操:多文件排序、混排与画廊封面控制 #

要把 Files & media 用成可靠的视觉与交付中枢,建议在操作层面统一以下四项细节规范(画廊与表格视觉调优另见 Notion 画廊视图与表格视图高阶排版实战 与 画廊视图官方指南):

  1. 严格控制第 1 位文件顺序(决定 Gallery 封面显示):
    • 同一单元格允许上传多个文件(例如 主视觉预览图.webp + 源文件.fig + 印刷PDF.pdf)。
    • Notion 的画廊卡片预览机制只会读取列表中第 1 个文件。如果第 1 位放的是 .zip 或 .docx 等非图像文件,画廊卡片就会显示为空白灰框!
    • 修正动作:点击单元格展开文件列表,按住封面图左侧的 ⋮⋮ 拖拽图标将其拖到最顶部第一位,画廊卡片封面即刻刷新渲染。
  2. 善用 Replace 原地替换而非“先删后传”:
    • 当合同修订至 v2 或设计图微调时,切勿直接删除旧文件再传新文件(在多人并发编辑或关联视图中容易出现短暂空窗);应点击文件右侧 ··· -> Replace,原地替换为最新文件并同步通过 ··· -> Rename 规范命名为 客户简称_合同类型_v2.pdf。
  3. 单格“原生直传 + Embed link 外链”混合挂载:
    • 点击 Files & media 单元格后,面板上方提供 Upload 与 Embed link 两个标签页。你可以在同一格内先把轻量的审阅缩略图通过 Upload 上传(供画廊卡片快速预览),再切换 Embed link 挂载一份几百 MB 的阿里云盘/Cloudflare R2 大文件直链,既规避免费版 5MB 上限(突破方案详见 Notion 文件上传限制突破与排障实战),又保留了完整检索入口。
  4. 开启 Crop 比例校验与 Fit image 防裁切:
    • 在 Gallery 视图打开 ··· -> Layout -> Fit image,避免产品原型截图或财务凭证在默认 16:9 裁切模式下被切掉关键边角数字。

三、Notion API File Upload(原生文件直传)三步流程与混合写库架构 #

在早期的 Notion API 版本中,开发者只能向 files 属性传入外部公开链接(type: "external"),无法直接把本地或服务器上的私有 PDF 发票、生成报表真正传进 Notion 托管存储。如今官方推出的 File Upload API(/v1/file_uploads) 彻底打通了自动化原生文件入库链路(接口鉴权基线参阅 创建 Notion API 集成指南 与 Notion API 2025-09-03 多源数据库迁移实战):

1. 原生直传三步标准流水线(适用于 ≤ 20MB 单次上传) #

  1. Step 1:创建上传会话(Create a file upload)
    • 请求 POST https://api.notion.com/v1/file_uploads,携带请求头 Authorization: Bearer <TOKEN> 与 Notion-Version: 2025-09-03;
    • 请求体指定文件名与 MIME 类型:{ "mode": "single_part", "filename": "2026Q4_验收报告.pdf", "content_type": "application/pdf" },接口将返回唯一的 id(即 file_upload_id)及上传端点 upload_url。(若单文件超过 20MB,需将 mode 设为 "multi_part" 并声明 number_of_parts,分片发送后再调用 /complete 接口合并)。
  2. Step 2:发送文件二进制流(Send file contents)
    • 向 POST https://api.notion.com/v1/file_uploads/{file_upload_id}/send 发送 multipart/form-data 请求,表单字段名固定为 file,放入本地二进制文件流;
    • 上传完成后,该会话状态变为 uploaded。注意未及时绑定到页面或块的上传会话会在短期窗口后自动失效清理。
  3. Step 3:将 file_upload_id 绑定到数据库 Files & media 属性
    • 调用 PATCH https://api.notion.com/v1/pages/{page_id}(或在 POST /v1/pages 新建记录时传入):
{
  "properties": {
    "交付附件": {
      "files": [
        {
          "type": "file_upload",
          "file_upload": {
            "id": "a1b2c3d4-xxxx-xxxx-xxxx-1234567890ab"
          },
          "name": "2026Q4_验收报告.pdf"
        }
      ]
    }
  }
}

重要工程提醒:通过 PATCH 更新 files 数组属于全量覆盖操作!如果该单元格原本已经有历史附件,脚本必须先 GET /v1/pages/{page_id} 读取原有条目(原生上传记录对应 file_upload / file,外链对应 external),再将新上传的 file_upload 对象追加进数组尾部,避免把历史文件意外覆盖抹除。


四、Formula 2.0 实战:交付物缺失拦截、格式校验与临时链接门禁 #

在数据库设计中(规范见 Notion 数据库架构速查手册),利用 Formula 2.0 的 lets()、empty()、.length()、.map()、.filter() 与 style()(函数索引参阅 Formula 2.0 函数与正则速查手册 与 数据库公式指南),可直接对 Files & media 属性建立三层自动化风控门禁:

  • 检测“已进入审核/已完成状态但附件为空”的漏交违规;
  • 检测交付物数量是否达到要求(如结项至少需 2 份文件:设计稿 + 确认单);
  • 检测是否误将带 amazonaws.com / X-Amz-Signature 的临时签名 URL 当作永久外链粘贴进 Embed link,或存在未加密 http:// 明文外链。
lets(
  files, prop("交付附件"),
  fileCount, files.length(),
  status, prop("当前状态"),
  isDoneOrReview, status == "待验收" || status == "已完成",
  /* 将文件列表映射为可检测字符串,排查临时签名链或非 HTTPS 明文外链 */
  fileTexts, files.map(format(current)),
  hasTempSignedUrl, fileTexts.filter(current.test("(?i)(amazonaws\\.com|X-Amz-Signature)")).length() > 0,
  hasInsecureHttp, fileTexts.filter(current.test("(?i)^http://")).length() > 0,
  hasPdfOrDoc, fileTexts.filter(current.test("(?i)\\.(pdf|docx|xlsx|zip)(\\?|$)")).length() > 0,

  ifs(
    isDoneOrReview && empty(files),
      style("🚨 禁止无附件结单 · 请立即上传或挂载交付物", "red", "bold", "red_background"),
    hasTempSignedUrl,
      style("🔴 含临时 S3 签名外链 · 1 小时后将失效,请改用原生上传或 R2 永久域名", "red", "bold", "red_background"),
    hasInsecureHttp,
      style("🟠 含非加密 HTTP 外链 · 建议升级为 HTTPS 防止浏览器拦截预览", "orange", "bold", "yellow_background"),
    status == "已完成" && fileCount < 2,
      style("🟡 交付附件不足 2 份(当前 " + format(fileCount) + " 份)· 请补齐归档材料", "yellow", "bold"),
    status == "已完成" && !hasPdfOrDoc,
      style("🔵 仅含纯图片或未知外链 · 请确认是否漏传 PDF/压缩包终稿", "blue"),
    empty(files),
      style("⚪ 进行中待上传交付物", "gray"),
    style("🟢 交付附件合规(已挂载 " + format(fileCount) + " 份文件)", "green", "bold", "green_background")
  )
)

视图闭环配置:新建一个 🚨 缺件待补齐 过滤视图(筛选技巧参阅 视图、过滤与排序指南),设置筛选条件 附件合规门禁 contains 禁止无附件结单 OR 附件合规门禁 contains 失效,每周五例会前 3 分钟一键清零遗漏交付物。


五、高频故障与导出迁移避坑清单 #

  1. 为什么把数据库导出为 CSV 后,Files & media 列里的链接过一会儿就打不开了?
    • 根因:导出为 CSV(操作参阅 将数据库导出为 CSV 指南)时,Notion 仅写入文本表格,不会打包二进制附件,列中输出的是带限时签名的 AWS S3 URL,过期即报 403 AccessDenied。
    • 应对:若需要完整带附件本地冷备份,必须在右上角 ··· -> Export 选择 Markdown & CSV 或 HTML 格式,并务必开启 Include subpages(或通过 Notion API 在获取页面后 1 小时内立即下载转存至本地/OSS)。
  2. 为什么点击 Files & media 里的 .docx 或 .xlsx 文件,总是直接下载而无法在线预览?
    • 根因:Notion 浏览器内联预览器原生支持常见图片(PNG/JPG/WebP/GIF)、PDF、MP3/MP4 音视频;对于 Office 二进制文档与压缩包,浏览器会统一触发下载动作。
    • 应对:团队内部高频审阅的规范文件建议导出为 PDF 上传,或者将协同编辑中的文档保留为飞书/Google Docs 外链并通过 Embed link 挂载。
  3. 为什么从外部系统批量导入 CSV 到 Files & media 列后,单元格变成了一串纯文本而不是可点击文件?
    • 根因:导入 CSV 前若未在目标数据库提前把列类型设为 Files & media,或者同一格塞入了多个未按规则分隔、且不带有效 http(s):// 协议头的字符串,系统会将其降级识别为普通文本。务必先建好 Files & media 列再执行导入映射(更多排查参阅 Notion 常见故障诊断手册)。

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。