本文详解 notion api 创建页面时返回 400 错误的根本原因——关键在于属性（properties）字段必须严格匹配数据库中各字段类型所要求的数据结构，尤其是标题（title）、富文本（rich_text）、url 等非纯字符串字段不可直接传值。
在使用 Notion API 的 pages.create() 方法时，一个高频且极易被误导的错误是：HTTP 400 响应伴随类似 body.properties.Link.id should be defined, instead was undefined 的报错信息。该错误看似指向缺失 ID 或元数据字段，实则根本原因在于——你向某个数据库属性传递了不符合其类型规范的值结构。
Notion 数据库中的每个属性（Property）都有明确的类型（如 Title、URL、Rich Text、Number、Select、Relation、Checkbox 等），而 API 要求你在 properties 对象中为每种类型提供标准化的对象结构，而非原始值。例如：
- ✅ Title 类型必须使用 { title: [...] } 结构；
- ✅ Rich Text（如 Notes、Year）必须使用 { rich_text: [...] }；
- ✅ URL 类型必须使用 { url: "https://..." }（注意：协议不能省略）；
- ❌ 不可将 Name 写成 [ { text: { content: "..." } } ]（这是旧版或错误嵌套）；
- ❌ 不可将 Link 直接赋值为 "www.google.com"（缺少 url 包裹，且无 https:// 协议）。
以下是修正后的完整示例代码（已通过 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: {
// ✅ Title 字段：必须用 { title: [...] }
Name: {
title: [
{
text: { content: 'Test name' },
},
],
},
// ✅ URL 字段：必须用 { url: "https://..." }，协议不可省略
Link: {
url: 'https://www.google.com', // ⚠️ 注意：www.google.com → 400；https://www.google.com → ✅
},
// ✅ Rich Text 字段：必须用 { rich_text: [...] }
Notes: {
rich_text: [
{
text: { content: 'sample notes' },
},
],
},
Year: {
rich_text: [
{
text: { content: '2020' },
},
],
},
},
});
console.log('✅ Page created:', response.url);
} catch (error) {
console.error('❌ API Error:', error.status, error.code, error.message);
// 建议：打印完整 error.body 查看具体校验失败项
if (error.body) console.error('Response body:', error.body);
}
}
main();? 关键注意事项：
- URL 必须带协议："www.google.com" 会触发 400；必须写为 "https://www.google.com" 或 "http://..."；
- Title 和 Rich Text 是数组：即使只有一段文本，也必须包裹在 [] 中；
- 字段名大小写敏感：确保 Name、Link 等 key 与 Notion 数据库中实际显示的属性名称完全一致（含空格、大小写）；
- 检查集成权限：确保你的 Integration 已被添加到目标数据库，并拥有 Can edit 权限；
- 调试技巧：启用 console.error(error.body) 可获取更精准的字段校验失败提示（如 body.properties.Year.type 不匹配）；
- Relation / Checkbox / Date 等类型：需遵循各自文档结构（例如 Relation 需传 relation: [{ id: "xxx" }]，Checkbox 需传 checkbox: true/false）。
总结：Notion API 的 400 错误常因“类型结构失配”引发，而非认证或权限问题。始终以 官方属性值参考文档 为准，为每种字段类型构造精确的嵌套对象，即可稳定创建页面。
