本文详解 notion api 创建页面时因属性类型误用导致 400 错误的根本原因，重点纠正 `title`、`rich_text`、`url` 等字段的嵌套结构误区，并提供可直接运行的修复代码与关键注意事项。
在使用 Notion API 创建数据库页面（notion.pages.create）时，一个高频踩坑点是：错误地将所有属性值统一用数组形式（如 Name: [{ text: { content: “…” } }]）传入，而忽略了不同属性类型对顶层键名和数据结构的严格要求。你遇到的 body.properties.Link.id should be defined 这类报错看似指向缺失字段，实则是 API 因结构不匹配提前校验失败——它根本没解析到 Link 的实际值，而是发现该属性对象不符合任何已知类型模式，于是回退到内部字段校验逻辑并抛出误导性提示。
核心规则如下：
- ✅ 标题（Title）属性：必须使用 title 作为顶层键，其值为 text 对象数组（即使只有一项）；
- ✅ 富文本（Rich Text）属性（如 Notes、Year）：必须使用 rich_text 作为顶层键，值同为 text 对象数组；
- ✅ URL 属性（如 Link）：直接使用 url 作为顶层键，值为字符串（注意：需含协议，如 https://，否则 Notion 可能拒绝）；
- ❌ 禁止混用：不可将 title 或 rich_text 写成数组（如 Name: […]），也不可将 url 包裹进 text 结构中。
以下是修正后的完整可运行示例（已适配最新 Notion API v1）：
const { Client } = require('@notionhq/client'); const notion = new Client({ auth: process.env.NOTION_TOKEN, }); async function main() { try { const response = await notion.pages.create({ parent: { type: 'database_id', database_id: process.env.DB_ID, }, properties: { Name: { title: [ { text: { content: 'Test name', }, }, ], }, Link: { url: 'https://www.google.com', // ✅ 必须带 https:// 协议 }, Notes: { rich_text: [ { text: { content: 'sample notes', }, }, ], }, Year: { rich_text: [ { text: { content: '2020', }, }, ], }, }, }); console.log('✅ Page created successfully:', response.url); } catch (Error) { console.error('❌ Failed to create page:', error.message); // 建议打印完整 error.body 用于调试 if (error.body) console.error('Response body:', error.body); } } main();? 关键注意事项：
- 协议强制要求：url 字段值必须包含 http:// 或 https://，www.google.com 会被拒绝，应写为 https://www.google.com；
- 数据库权限检查：确保集成（Integration）已在目标数据库中被明确添加为“可编辑”成员（Notion UI → Database → ··· → Add connections）；
- 属性名称大小写敏感：Name、Link 等必须与数据库中实际 Property 名称完全一致（包括空格和大小写）；
- Relation / checkbox 等复杂类型：需按官方文档对应结构书写（如 relation: { database_id: “…”, … }），切勿尝试用 text 数组模拟；
- 调试技巧：启用 console.error(error.body) 可获取更精准的验证错误位置，比仅看 error.message 更有效。
遵循上述结构规范后，90% 以上的 400 Bad Request 页面创建失败问题即可解决。记住：Notion API 的属性不是“自由格式”，而是强契约式 Schema —— 每个 property type 都有唯一合法的顶层键名与嵌套结构，这是避免误导性报错的关键。