Notion Formula 2.0 常见语法报错全景排查与调试进阶实战:从 Type Mismatch、Null 空值穿透到复杂链式公式单步诊断指南

2026 年 11 月 15 日

1. Formula 2.0 类型系统与报错机制总览 #

Notion 在升级至 Formula 2.0 引擎后,不仅引入了点语法(Dot Notation)和局部变量(lets()),更在底层推行了严格的静态类型系统。在旧版 1.0 中,引擎会尝试对某些不合规操作进行隐式宽容处理;而在 2.0 中,只要类型不匹配、空值未防御或列表嵌套出现偏差,公式编辑器就会立即触发红线报错并阻断保存。

1.1 强类型静态检查与运行时求值的双重防线 #

Formula 2.0 的校验逻辑分为两层:

  1. 静态解析期报错(Static Compilation Errors):发生在公式编辑输入框内。例如传入参数类型与函数签名不符(如 length() 传入了纯数字)、括号未成对闭合、或者 lets() 中定义的变量未在最终结果表达式中使用。此时公式框下方会直接显示红色警告,并禁用“Done”保存按钮。
  2. 运行时空值与溢出异常(Runtime Semantic Issues):公式本身语法合规,但当某一行数据中的特定属性为空(Null/Empty)、跨库关联被断开或日期解析失败时,导致结果列呈现空白、NaN 或非预期的计算结果。

1.2 高频报错分类矩阵 #

错误类别 典型报错提示信息 根本诱因 易发场景 核心防御手段
类型不匹配 Type mismatch: expected Text but got Number 隐式类型转换失效,直接混合不同类型操作 数字与字符串用 + 拼接,布尔与文本混用 使用 format()、toNumber() 显式转型
空值穿透 Cannot read properties of null 或公式结果异常为空 目标属性为空时直接调用后续链式方法 对未填写的日期取 year(),对未关联的属性取子属性 empty() 判断预检,或使用 ifs() 短路保护
容器类型混淆 Function expects a list but got a single item 对非数组属性使用数组高阶函数,或反向混淆 对单值文本执行 .map(),对 Relation 遗漏 .first() 明晰标量与列表边界,善用 .flat() 扁平化
作用域未闭合 Variable 'xxx' is declared but never read lets() 变量配对遗漏最终求值表达式 长公式末尾多写逗号或漏写计算主体 遵循两两配对排版,末尾独立表达式求值
日期运算溢出 dateBetween requires valid Date values 开始/结束日期包含空值或时序颠倒 计划结束时间早于开始时间,跨时区转换偏差 配合 min()/max() 校验日期合法性

2. 6 大高频致命报错深度剖析与修复范式 #

2.1 报错一:Type mismatch 类型不匹配 #

故障重现 #

在旧版 1.0 中,"当前金额:" + prop("Amount") 会自动将数字转换为字符串。但在 Formula 2.0 中,此写法会立即抛出: Type mismatch: Cannot add Number to Text.

根因剖析 #

Formula 2.0 中的 + 运算符被严格重载:

  • 当两侧均为 Text 时,执行字符串拼接;
  • 当两侧均为 Number 时,执行算术加法;
  • 两侧类型不同时,系统拒绝隐式转换。

标准修复代码 #

/* ❌ 错误代码 */
"当前结余: " + prop("Balance") + " 元"

/* ✅ 修复代码: 显式调用 format() 或 style() */
"当前结余: " + format(prop("Balance")) + " 元"

/* 💡 高阶优雅方案: 富文本样式包装 */
style("当前结余: ", "gray") + style(format(prop("Balance")), "bold", "blue") + style(" 元", "gray")

2.2 报错二:Null / Empty 空值穿透异常 #

故障重现 #

当尝试从“关联合同”中获取签署日期并计算剩余天数时,若某些行尚未关联合同,公式直接导致整行结果空白甚至显示故障: dateBetween(prop("Contract").first().prop("Sign Date"), now(), "days")

根因剖析 #

当 prop("Contract") 为空数组时,.first() 返回空实体,继续读取 .prop("Sign Date") 时会返回 null,导致外部 dateBetween 接收到非法日期参数。

标准修复代码 #

采用“前置守卫条件(Guard Clauses)”对空值进行拦截:

/* ❌ 脆弱代码: 未做空值防御 */
dateBetween(prop("Contract").first().prop("Sign Date"), now(), "days")

/* ✅ 健壮代码: 运用 lets() 与 ifs() 分级校验 */
lets(
  contract, prop("Contract").first(),
  if(
    empty(contract),
    "⚪ 尚未关联合同",
    lets(
      signDate, contract.prop("Sign Date"),
      if(
        empty(signDate),
        "🟡 合同尚未签署",
        lets(
          daysLeft, dateBetween(signDate, now(), "days"),
          if(daysLeft >= 0, "🟢 剩余 " + daysLeft + " 天", "🔴 已逾期 " + abs(daysLeft) + " 天")
        )
      )
    )
  )
)

2.3 报错三:List vs Scalar 列表与标量混淆 #

故障重现 #

在处理关联任务时,尝试直接获取所有子任务的负责人姓名: prop("Sub-items").prop("Assignee").name() 系统报错:Cannot call name() on a list of items.

根因剖析 #

prop("Sub-items") 是一个页面对象列表(List of Pages),通过 .prop("Assignee") 得到的也是一个二级列表(List of Lists of People)。此时直接对其调用针对单个对象的 .name() 方法,必然引发类型混淆。

标准修复代码 #

必须使用 .map() 遍历并在必要时调用 .flat() 进行列表扁平化:

/* ❌ 错误代码 */
prop("Sub-items").prop("Assignee").name()

/* ✅ 修复代码: 展开映射并去重提取 */
prop("Sub-items")
  .map(current.prop("Assignee"))
  .flat()
  .unique()
  .map(current.name())
  .join("、")

2.4 报错四:lets() 变量作用域与语法结构错位 #

故障重现 #

编写多层变量时,编辑器提示 Expected 2n+1 arguments in lets() 或变量未找到。

根因剖析 #

lets() 函数的签名规则非常固定:必须传入奇数个参数!

  • 参数 1: 变量名 1(文本字面量,无需引号)
  • 参数 2: 表达式 1
  • 参数 3: 变量名 2
  • 参数 4: 表达式 2
  • ...
  • 最后一个参数(第 2n+1 个参数): 最终的求值输出表达式。

标准修复规范 #

/* ❌ 常见失误: 末尾遗漏了最终求值表达式,或者多写了一个逗号 */
lets(
  a, 10,
  b, 20,
) // 报错!

/* ✅ 规范结构 */
lets(
  a, 10,
  b, 20,
  /* 最终输出表达式 */
  a + b
)

2.5 报错五:日期与跨时区运算负数陷阱 #

故障重现 #

使用 dateBetween(date1, date2, "days") 时,很多用户发现结果与预期正负号完全相反。

根因剖析 #

Notion 官方对 dateBetween(d1, d2, unit) 的底层定义为:d1 - d2。 也就是说:

  • 如果 d1 是未来时间(晚于 d2),结果为正数;
  • 如果 d1 是过去时间(早于 d2),结果为负数。

标准修复范式 #

/* 规范目标: 计算截止日期(Deadline)距离现在的剩余天数 */
lets(
  deadline, prop("Deadline"),
  if(
    empty(deadline),
    "⚪ 未设定排期",
    lets(
      diff, dateBetween(deadline, now(), "days"),
      ifs(
        diff > 0, "⏳ 剩余 " + diff + " 天",
        diff == 0, "🔥 今日截止!",
        "🚨 超期滞后 " + abs(diff) + " 天"
      )
    )
  )
)

3. 高阶公式排错四步单步调试法(Scaffold Debugging) #

当面对数十行甚至上百行的复杂 Formula 2.0 时,若公式无法保存或输出异常,盲目修改往往使问题复杂化。推荐采用以下系统化单步调试法:

3.1 步骤一:探针输出法(Probe Output) #

利用 lets() 最后一个参数的即时求值特性,将怀疑有异常的中间变量直接作为公式的最终返回值进行查看:

lets(
  rawList, prop("Related Tasks"),
  step1_filtered, rawList.filter(current.prop("Status") == "Done"),
  step2_names, step1_filtered.map(current.prop("Name")),
  
  /* 调试探针: 先不要返回最终业务逻辑,直接输出 step1_filtered.length() 验证第一步是否取到了数据 */
  "【调试输出】已过滤数量: " + format(step1_filtered.length()) + " | 提取名称: " + step2_names.join(",")
)

3.2 步骤二:强制结构化多行缩进与语义化命名 #

切忌将复杂公式写成一行紧凑字符串。充分利用回车和缩进,将每一个逻辑单元独立成行:

  • 每个变量名使用小驼峰(camelCase)并具备明确业务含义;
  • 每一个开括号 ( 换行缩进 2 格,闭括号 ) 与声明对齐;
  • 利用 /* 注释内容 */ 标明业务阶段。

3.3 步骤三:脚手架辅助属性拆解法(Scaffold Columns) #

当某个链式运算实在难以确定哪一段崩溃时:

  1. 新建一个临时的 Formula 属性,命名为 _Debug_1,仅编写前半段提取逻辑;
  2. 确认 _Debug_1 在所有行都能正常渲染出预期数据;
  3. 新建 _Debug_2 测试中间过滤与运算逻辑;
  4. 测试无误后,再将两段代码通过 lets() 合并为主公式,并删除临时调试列。

4. 常见 Formula 2.0 报错速查对照表 #

场景代码示例 错误表现 根因分类 一键修复方案
prop("Done") ? "完成" : "未完" Syntax error: Expected ')' 语法不支持三元表达式 改用 if(prop("Done"), "完成", "未完")
prop("Price") * "0.8" Cannot multiply Number by Text 字符串参与数学运算 改用 prop("Price") * 0.8 或 toNumber("0.8")
prop("Tags").contains("紧急") 始终返回 false 或报错 对多选属性包含判断语法错误 改用 prop("Tags").includes("紧急")
prop("Date").formatDate("YYYY-MM-DD") Function not found on Date 点语法函数位置颠倒 改用 formatDate(prop("Date"), "YYYY-MM-DD")
prop("Relations").sum() sum() expects a list of numbers 对包含对象的列表直接求和 改用 prop("Relations").map(current.prop("Amount")).sum()

5. 生产级健壮性设计准则与站内延伸资源 #

5.1 零崩溃设计三大铁律(Zero Crash Rules) #

  1. 永远假设属性值可能为空:只要不是系统自动生成的 Created time 或 id(),任何人工填写的属性都必须包裹在 empty() 校验之内。
  2. 数组操作优先考虑空集合:对于 .first()、.last(),必须考虑当列表长度为 0 时的回退值处理,避免链式访问产生非法调用。
  3. 关键公式版本注释归档:在公式头部通过多行注释 /* Version: 1.2, Author: Team, Updated: 2026-11 */ 记录迭代履历,便于后续团队交接维护。

5.2 站内相关技术资源 #

深入掌握 Notion 数据库公式、底层架构与高级排错,建议阅读以下站内深度指南:

❓ 常见问题与答疑 (FAQ)

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

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