本文详解 notion api 创建页面时返回 400 错误的根本原因：属性值结构不匹配（如将 `title` 或 `rich_text` 字段误写为数组形式），并提供符合官方 schema 的完整代码示例与关键注意事项。
在使用 Notion API 创建数据库页面（notion.pages.create）时，一个高频却极易被忽略的错误是：属性（property）值的嵌套结构不符合 Notion 的严格 Schema 要求。你遇到的 400 Bad Request 错误（如 body.properties.Link.id should be defined, instead was undefined）并非因权限、ID 或 Token 问题，而是因为 API 将你传入的 Link: { url: "..." } 等非文本类属性，错误识别为“未初始化的空对象”——其根本原因在于：所有非纯字符串类型的属性（包括 title、rich_text、url、checkbox、relation 等）都必须以明确的类型键（type key）作为外层包装，且该键不可省略或错位。
例如，Name 字段在数据库中若定义为 Title 类型，则其值必须是 { title: [...] }；若定义为 Text（即 Rich Text）类型，则必须是 { rich_text: [...] }；而 Link 字段若为 URL 类型，则必须是 { url: "https://..." } ——注意：url 是顶层键，不是 rich_text 的子字段，也不接受数组形式。
以下是修正后的标准写法（关键变更已加注释）：
const { Client } = require("@notionhq/client");
const notion = new Client({
auth: process.env.NOTION_TOKEN,
});
async function main() {
try {
await notion.pages.create({
parent: {
type: "database_id",
database_id: process.env.DB_ID, // ✅ 确保 DB_ID 是有效 UUID 格式（含连字符）
},
properties: {
// ✅ Title 类型：必须用 { title: [...] }
Name: {
title: [
{
text: { content: "Test name" },
},
],
},
// ✅ URL 类型：必须用 { url: "https://..." }，且协议不可省略
Link: {
url: "https://www.google.com", // ⚠️ 原代码缺少 "https://"，Notion 会拒绝无效 URL
},
// ✅ Rich Text 类型：必须用 { rich_text: [...] }
Notes: {
rich_text: [
{
text: { content: "sample notes" },
},
],
},
// ✅ 同样适用于其他 Rich Text 字段（如 Year）
Year: {
rich_text: [
{
text: { content: "2020" },
},
],
},
},
});
console.log("✅ Page created successfully!");
} catch (error) {
console.error("❌ Failed to create page:", error.body?.message || error.message);
}
}
main();⚠️ 关键注意事项：
- URL 必须带协议：url 字段值必须为完整 URL（如 "https://google.com"），"www.google.com" 或 "google.com" 会被视为非法，导致 400；
- 类型键不可省略：Name: [...]（数组）或 Name: { text: ... } 均非法；必须显式声明 title / rich_text / url / checkbox 等类型键；
- 数据库字段名需完全一致：properties 中的键名（如 "Name"、"Link"）必须与 Notion 数据库中对应列的精确显示名称（区分大小写、空格）完全匹配；
- Relation / Checkbox 等复杂类型需额外结构：例如 Relation 需传 { relation: [{ id: "xxx-xxx-xxx" }] }，Checkbox 需 { checkbox: true }，不可直接传布尔值或 ID 数组；
- 调试建议：启用 console.error(error.body) 可获取 Notion 返回的详细校验错误（如字段类型不匹配提示），比仅看 error.message 更精准。
遵循上述结构规范后，你的页面创建请求将严格符合 Notion API 的 OpenAPI Schema，彻底规避误导性的 undefined 字段报错。记住：Notion API 不接受“约定优于配置”，一切以 Property Value Objects 文档 中定义的 JSON 结构为准。
