将 Notion 数据库导出为 Obsidian 兼容的 Markdown 文件的专业 Python 工具。
- ✅ 完整数据库导出：支持将 Notion 数据库条目转换为 Obsidian Markdown 文件
- ✅ 智能属性转换：自动处理 YAML frontmatter，包括日期时间格式的优化
- ✅ 中文字段映射：智能转换中文属性名（特别是时间相关字段）为英文
- ✅ 格式保留：保留 Notion 页面的原始格式和内容结构
- ✅ 交互式界面：友好的命令行菜单系统，支持测试和完整导出模式
- ✅ 错误处理：完善的异常处理机制，精确定位问题
- ✅ 重试机制：API请求失败自动重试，支持指数退避策略
- ✅ 速率限制：自动处理Notion API的速率限制
- ✅ 日志系统：完整的日志记录，便于问题排查和监控
- ✅ 字段转换表：直观显示 Notion → Obsidian 属性类型映射关系
- ✅ 空值属性处理：智能过滤空值字段，保持输出文件整洁
- ✅ 转换预览：导出前展示字段转换情况，确认后再执行
- ✅ 多种配置方式：支持配置文件和环境变量
- ✅ 缓存机制：页面标题缓存，避免重复API调用
- ✅ 导出统计：实时显示处理进度和结果统计
- ✅ 模块化架构：重构后的专业架构，易于扩展和维护
- 基础类型：title, rich_text, number, select, multi_select
- 时间类型：date, created_time, last_edited_time
- 用户类型：created_by, last_edited_by, people
- 高级类型：formula, relation, rollup, files
- 特殊类型：checkbox, url, email, phone_number
- 基础块：paragraph, heading_1/2/3
- 列表块：bulleted_list_item, numbered_list_item, to_do
- 特殊块：code, quote, divider
- 增强块：callout, toggle, embed, bookmark, image, file, video, audio, table
- 克隆仓库：
git clone https://github.com/Sherryyue24/NotionDBtoMD.git
cd NotionDBtoMD- 安装依赖：
pip install -r requirements.txt-
创建 Notion 集成
- 访问 Notion Developers
- 点击 "New integration"
- 填写集成名称并创建
- 复制生成的 API 密钥
-
分享数据库给集成
- 在 Notion 中打开要导出的数据库
- 点击右上角的 "Share" 按钮
- 在下拉菜单中找到并选择你创建的集成
-
获取数据库 ID
- 在浏览器中打开数据库
- 复制 URL 中的数据库 ID（32 位字符串）
-
配置程序
- 复制
config.example.py为user_config.py：cp config.example.py user_config.py
- 编辑
user_config.py文件，填入您的实际配置：NOTION_API_KEY = "your-api-key" DATABASE_ID = "your-database-id"
注意： 输出目录会自动设置为您的 Notion 数据库名称，无需手动指定。
- 复制
- 运行程序：
python main.py- 您将看到交互式菜单：
============================================================
🚀 Notion 数据库导出工具
将 Notion 数据库转换为 Obsidian Markdown 文件
============================================================
📋 请选择操作：
1. 🧪 测试转换（前5条记录）
2. 📦 转换全部记录
3. ⚙️ 显示配置信息
4. 📊 显示支持的块类型
5. 🔄 显示字段转换表
6. 🚪 退出程序
-
选择操作模式：
- 选项 1：测试转换前 5 条记录，验证配置和转换效果
- 选项 2：转换全部数据库记录
- 选项 3：查看当前配置信息
- 选项 4：查看支持的Notion块类型
- 选项 5：查看字段转换表，了解属性映射关系
- 选项 6：退出程序
-
转换后的文件将自动保存在以数据库名称命名的目录中，包含完整的统计信息
程序提供了强大的字段转换表功能，帮助您在导出前了解数据转换情况：
字段名 Notion类型 Obsidian类型 状态
--------------------------------------------------------------------------------
岗位类型 multi_select List ✅ 有值
工作方式 select Text ✅ 有值
评价 rich_text Text ⚪ 空值
URL url Text ✅ 有值
发布平台 relation List ⚪ 空值
状态 status Text ✅ 有值
名称 title Text ✅ 有值
- 转换前字段数: 数据库中定义的字段总数
- 有值字段数: 包含实际数据的字段数量
- 空值字段数: 为空的字段数量
- 最终输出字段数: 实际输出到 markdown 的字段数量
- 导出前确认: 在选项1或2进行导出时，自动显示字段转换预览
- 独立查看: 使用选项5单独查看字段转换表
- 调试分析: 了解哪些字段有数据，哪些为空
- 自动过滤: 空值字段不会出现在最终的 markdown 文件中
- 保持整洁: 避免输出
null或空值，保持文件干净 - 结构完整: 保留所有有意义的属性，确保数据完整性
程序会自动将包含"时间"的中文属性名转换为英文，例如：
- 上班时间 -> startwork_time
- 下班时间 -> endwork_time
- 开始时间 -> start_time
- 结束时间 -> end_time
- 创建时间 -> created_time 等
Notion属性：https://www.notion.com/help/database-properties#types-of-database-properties Obsidian属性：https://help.obsidian.md/properties
完全支持 Notion 所有 21 种属性类型和Obsidian属性的转换：
| Notion 属性类型 | Obsidian 属性类型 | 输出格式 | 示例 | 说明 |
|---|---|---|---|---|
| 📝 文本相关 | ||||
| Title | Text | 纯文本 | title: "我的笔记" |
提取富文本的纯文本内容 |
| Rich text | Text | 纯文本 | description: "这是描述" |
支持内部链接转换 |
| URL | Text | 链接地址 | website: "https://example.com" |
保持原始URL格式 |
| Text | 邮箱地址 | contact: "[email protected]" |
保持邮箱格式 | |
| Phone | Text | 电话号码 | phone: "+86 138 0000 0000" |
保持电话格式 |
| 🔢 数值相关 | ||||
| Number | Number | 数值 | score: 85 |
支持整数和小数 |
| Formula | Number/Text | 计算结果 | total: 100 |
根据公式结果类型决定 |
| ID | Text/Number | 唯一标识符 | id: "TASK-001" |
支持前缀+数字格式 |
| 📅 日期相关 | ||||
| Date | Date | ISO日期格式 | due: 2024-01-15 |
支持日期和日期时间 |
| Created time | Date | 创建时间戳 | created: 2024-01-15T10:30 |
自动生成 |
| Last edited time | Date | 编辑时间戳 | updated: 2024-01-15T15:45 |
自动更新 |
| 👥 人员相关 | ||||
| Person | List | 人员姓名列表 | assignee: ["张三", "李四"] |
支持多人员 |
| Created by | Text | 创建者姓名 | author: "张三" |
单个用户名 |
| Last edited by | Text | 编辑者姓名 | editor: "李四" |
单个用户名 |
| 🏷️ 选择相关 | ||||
| Select | Text | 选中标签 | status: "进行中" |
单个选项 |
| Multi-select | List | 标签列表 | tags: ["重要", "紧急"] |
多个选项 |
| Status | Text | 状态标签 | workflow: "待办" |
类似Select的状态管理 |
| 🔗 关联相关 | ||||
| Relation | List | 内部链接列表 | related: ["[[笔记1]]", "[[笔记2]]"] |
转换为Obsidian链接 |
| Rollup | Text | 汇总结果 | summary: "汇总信息" |
显示汇总计算结果 |
| 📎 其他类型 | ||||
| Checkbox | Checkbox | 布尔值 | completed: true |
真/假值 |
| Files & media | List | 文件名列表 | attachments: ["文档.pdf", "图片.jpg"] |
文件名称列表 |
| Button | Text | 按钮标识 | action: "Button" |
按钮配置信息 |
✅ 完全兼容: 所有 Notion 属性都能正确映射到 Obsidian 格式
✅ 类型保持: 数值、日期、布尔类型在转换后保持原有特性
✅ 链接转换: 关系属性自动转换为 Obsidian 内部链接
✅ 结构化: 使用标准 YAML frontmatter 格式，兼容其他工具
除了 config.py 文件，您也可以使用环境变量进行配置：
export NOTION_API_KEY="your-api-key"
export DATABASE_ID="your-database-id"
export OUTPUT_DIR="custom_output"
export LOG_LEVEL="DEBUG"您可以在程序中自定义字段映射规则，将中文字段名映射为英文：
# 程序会自动映射以下字段
field_mapping = {
"项目状态": "project_status",
"负责人": "assignee",
"优先级": "priority",
"开始时间": "start_time",
"结束时间": "end_time"
}控制空值字段的处理方式：
# 在配置中设置
config = Config(
notion_api_key="your-api-key",
database_id="your-database-id",
include_empty_properties=False, # 默认为False，过滤空值字段
# include_empty_properties=True, # 设为True则包含空值字段
)配置选项说明：
include_empty_properties=False(推荐): 空值字段不会出现在输出文件中，保持整洁include_empty_properties=True: 包含所有字段，但空值字段会被智能过滤，不显示为null
程序会自动生成详细的日志文件 notion_export.log，包含：
- API请求记录
- 错误信息和堆栈跟踪
- 处理进度和统计信息
- 性能监控数据
查看日志：
# 实时查看日志
tail -f notion_export.log
# 搜索错误信息
grep ERROR notion_export.log程序支持扩展新的Notion块类型转换器：
# 添加自定义块类型处理
def custom_block_converter(block):
# 自定义转换逻辑
return "转换后的markdown内容"
# 注册转换器
converter.register_converter("custom_block", custom_block_converter)- 分页处理：自动处理大型数据库的分页获取
- 并发控制：合理控制API请求频率，避免速率限制
- 错误恢复：自动重试失败的请求，确保数据完整性
- 权限检查：确保您有足够的 Notion API 访问权限
- 测试优先：建议先使用测试模式（选项 1）验证转换效果
- 时间预估：转换大量数据时可能需要较长时间，程序会显示进度
- 数据备份：建议定期备份 Obsidian 笔记
- 安全保护：
user_config.py文件包含敏感信息，请勿上传到公共仓库 - 网络稳定：确保网络连接稳定，程序会自动处理网络中断和重试
Q: API密钥错误
❌ Notion API错误 (状态码: 401): API密钥无效或已过期
💡 建议检查API密钥是否正确
Q: 数据库ID错误
❌ Notion API错误 (状态码: 404): 资源未找到，请检查数据库ID
💡 建议检查数据库ID是否正确
Q: 网络超时
- 程序会自动重试，请耐心等待
- 可以查看日志文件了解详细情况
- 如需调整超时设置，可修改配置参数
- 启用详细日志：设置环境变量
LOG_LEVEL=DEBUG - 查看统计信息：使用菜单选项查看导出统计
- 检查日志文件：查看
notion_export.log获取详细错误信息
notiondbtomd/
├── src/ # 核心模块 (重构后的专业架构)
│ ├── __init__.py # 包初始化，导出主要类
│ ├── exceptions.py # 自定义异常类 (4种异常类型)
│ ├── config.py # 配置管理类 (支持多种配置方式)
│ ├── property_converter.py # 属性转换器 (支持21种属性类型)
│ ├── block_converter.py # 块转换器 (支持15+种块类型)
│ └── notion_exporter.py # 主导出器 (协调转换流程)
├── main.py # 主程序入口 (交互式菜单界面)
├── user_config.py # 用户配置文件 (从config.example.py复制)
├── config.example.py # 配置文件模板
├── requirements.txt # Python依赖
├── LICENSE # MIT许可证
└── README.md # 使用说明
输出结构/
├── [数据库名称]/ # 自动创建的输出目录
│ ├── 页面1.md # 转换后的Markdown文件
│ ├── 页面2.md # 包含YAML frontmatter
│ └── ... # 所有导出的页面
└── notion_export.log # 详细日志文件
- 模块化设计: 每个功能独立为专门的类，职责清晰
- 异常处理: 4种自定义异常类型，精确错误定位
- 配置灵活: 支持文件配置、环境变量等多种方式
- 可扩展性: 易于添加新的属性类型和块类型支持
- 专业架构: 符合Python最佳实践的代码结构
- 🔌 Obsidian 插件版本: notion-obsidian-sync - 直接在 Obsidian 中使用，无需 Python 环境
- 智能缓存：避免重复API调用，提高处理速度
- 批量处理：支持大型数据库的高效导出
- 内存优化：分页处理，适合处理大量数据
- 网络优化：自动重试和速率限制处理
MIT License - 详见 LICENSE 文件
如果这个项目对您有帮助，请考虑：
- ⭐ 给项目加星
- 🔄 分享给其他用户
- 💬 在社区中分享使用体验
- 🐛 报告问题和建议改进