1. 项目概述：将你的知识库一键发布到云端
如果你和我一样，是个重度 Obsidian 用户，那么你的 Vault 里一定塞满了各种笔记、想法和项目资料。这些内容价值连城，但往往只沉睡在你的本地硬盘里。有没有想过，能像管理代码仓库一样，轻松地把选定的笔记发布成一个美观、可搜索的静态网站，并且拥有自己的专属域名？这就是obsidian-cloudflare-pages-skill这个 OpenClaw 技能要帮你解决的核心问题。
简单来说，它是一个自动化的工作流工具，能将你 Obsidian 笔记库（或任何 Markdown 文件夹）中的特定内容，通过 Quartz 静态网站生成器构建，并一键部署到 Cloudflare Pages 上。整个过程从配置、同步、构建到部署，全部通过命令行搞定，极大地简化了从笔记到公开知识库的发布流程。无论你是想建立一个公开的技术博客、一个团队内部的知识 Wiki，还是一个私人的学习笔记集，这个工具都能让你摆脱繁琐的部署细节，专注于内容创作本身。
2. 核心设计思路与方案选型
2.1 为什么是这套技术栈？
这个项目的设计思路非常清晰：利用成熟、免费或低成本的开源工具，构建一个高度自动化且安全的发布管道。我们拆开来看每个环节的选型考量：
源内容管理：ObsidianObsidian 以其强大的双向链接、本地优先和丰富的插件生态，成为了个人知识管理的首选。选择它作为内容源，意味着你可以继续在你最熟悉、最高效的环境里写作，无需改变习惯。工具只负责“发布”这个动作，而不干涉“创作”过程。
静态站点生成：QuartzQuartz 是一个专门为关联笔记（Zettelkasten）优化的静态网站生成器。它原生支持 Obsidian 式的双链语法
[[ ]]，能自动将笔记间的链接转化为网站内的超链接，并生成反向链接（Backlinks）面板。这对于呈现一个相互关联的知识网络至关重要，是其他通用 SSG（如 Hugo、Jekyll）需要额外配置才能实现的功能。部署平台：Cloudflare Pages这是整个方案的成本和易用性核心。Cloudflare Pages 提供免费的静态网站托管、全球 CDN、自动的 HTTPS 证书，并且与 Git 工作流深度集成。虽然本项目绕过了直接的 Git 集成，而是通过 Wrangler CLI 部署，但仍然享受其所有基础设施优势。选择它，意味着你几乎可以零成本拥有一个快速、安全的全球可访问网站。
自动化粘合剂：OpenClaw SkillOpenClaw 是一个自动化工作流平台，Skill 是其可复用的功能模块。将整个发布流程封装成一个 Skill，带来了几个关键好处：配置集中管理（所有设置在一个
config.json里）、流程标准化（通过init,wizard,run等命令提供一致体验）、环境隔离（技能有自己的依赖和.env文件）。这比写一堆散落的脚本要可靠和易于维护得多。
2.2 安全与可控性设计
从项目的更新日志和配置项可以看出，开发者对安全性和操作风险有着深刻的考虑，这也是一个生产级工具必备的素质：
SAFE_MODE与--dry-run：这是最重要的安全阀。SAFE_MODE=1会完全阻止对外部环境（Cloudflare）的写操作和潜在的破坏性本地操作。--dry-run参数则可以在执行任何实际文件操作或部署前，完整地预览所有将要执行的步骤。在操作不熟悉的系统或关键数据前，务必使用这些选项。- 同步模式选择 (
syncMode)：提供了mirror和append两种模式。mirror模式会使用rsync的--delete选项，使目标目录成为源目录的精确镜像，这可能会删除目标目录中存在而源目录中没有的文件。append模式则只添加或更新文件，不会删除任何已有文件。对于初期或不希望冒任何数据丢失风险的用户，建议从append模式开始。 - 凭证管理：强烈建议通过
.env文件管理 Cloudflare API Token、Account ID 以及 Basic Auth 的账号密码。将.env文件加入.gitignore，避免敏感信息泄露。配置文件 (config.json) 中只应引用环境变量名，而不是写死实际值。
注意：即使提供了 Basic Auth 功能，它也只是 HTTP 层面的基础访问控制。对于真正敏感的内容，你应当考虑更严格的保护措施，例如将整个站点部署在 Cloudflare Access 之后，或者根本不要将其发布到公网。
3. 从零开始的完整实操指南
3.1 环境准备与依赖安装
在运行技能之前，你需要一个可用的基础环境。以下步骤假设你使用的是 macOS 或 Linux 系统（Windows 用户建议使用 WSL2）。
1. 安装 Node.js 和 npmQuartz 4 需要 Node.js 环境。建议使用 nvm 来管理 Node 版本，避免权限问题。
# 安装 nvm (Node Version Manager) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 重新打开终端或运行 source ~/.bashrc (或 ~/.zshrc) # 安装最新的 LTS 版本 Node.js nvm install --lts nvm use --lts # 验证安装 node --version npm --version2. 安装 rsyncrsync是文件同步的核心工具，在 macOS 上通常已预装，Linux 可通过包管理器安装。
# Ubuntu/Debian sudo apt-get install rsync # CentOS/RHEL/Fedora sudo yum install rsync # 或 sudo dnf install rsync3. 安装 Wrangler CLIWrangler 是 Cloudflare 的官方命令行工具，用于管理 Workers 和 Pages 项目。
npm install -g wrangler # 验证安装 wrangler --version4. 登录 Cloudflare 并获取凭证这是连接 Cloudflare 账户的关键步骤。
# 通过命令行登录，会打开浏览器进行授权 wrangler login登录成功后，你需要获取两个关键信息：
- Account ID：在 Cloudflare 仪表板右下角，点击你的账户名称，进入“概述”页面，在右侧“API”区域即可找到“账户 ID”。
- API Token：你需要创建一个具备 Pages 编辑权限的 Token。
- 进入 Cloudflare 仪表板，右上角头像 -> “我的个人资料”。
- 选择 “API 令牌” 标签页。
- 点击 “创建令牌”。
- 使用 “编辑 Cloudflare Pages” 模板。
- 在“账户资源”中，选择包含你 Pages 项目的账户。
- 继续并创建令牌。务必立即复制并妥善保存这个 Token，它只会显示一次。
3.2 技能初始化与配置向导
假设你已经通过 OpenClaw 的机制安装或克隆了obsidian-cloudflare-pages-skill到你的技能目录。
1. 进入 OpenClaw 工作区
cd ~/.openclaw/workspace2. 初始化配置文件首次运行时，需要从模板创建配置文件。
node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js init这个命令会在skills/obsidian-cloudflare-pages/config/目录下生成一个config.json文件，其内容拷贝自config.example.json。
3. 运行交互式配置向导这是最推荐的方式，向导会一步步引导你完成所有必要设置。
node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js wizard向导通常会询问以下信息，请提前准备好：
- Obsidian Vault 路径：你的笔记库在本地的绝对路径（如
/Users/yourname/Documents/ObsidianVault）。 - 要发布的文件夹：Vault 中哪些文件夹的内容需要被发布（例如
Clippings,Public）。 - 要排除的文件夹：哪些文件夹应被忽略（例如
Private,.obsidian,Templates）。 - Cloudflare 项目名：在 Cloudflare Pages 上创建或使用的项目名称。
- 生产环境域名：你计划绑定的自定义域名（如
notes.yourdomain.com）。 - 是否启用 Basic Auth：如果启用，需要设置用户名和密码。
4. 配置环境变量（存储敏感信息）永远不要将 API Token 等秘密写入config.json。使用.env文件。
cd skills/obsidian-cloudflare-pages cp .env.example .env # 使用你喜欢的文本编辑器编辑 .env 文件，例如 nano 或 vim nano .env在.env文件中填入你的真实信息：
# Cloudflare 凭证 CLOUDFLARE_API_TOKEN=你的_API_Token_粘贴在这里 CLOUDFLARE_ACCOUNT_ID=你的_Account_ID_粘贴在这里 # 可选：如果向导中配置了 Basic Auth 并选择使用环境变量，在这里设置 BASIC_AUTH_USERNAME=你的用户名 BASIC_AUTH_PASSWORD=你的强密码3.3 首次发布全流程解析
配置完成后，你可以执行一次完整的发布流程来验证一切是否正常。
1. 运行健康检查在正式发布前，先检查环境和配置是否有问题。
node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js doctor这个命令会检查 Node 版本、rsync、wrangler是否存在，以及关键的路径和配置项是否有效。根据输出修复任何错误。
2. 初始化 Quartz 工作区技能需要一个 Quartz 项目目录来构建网站。
node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js setup-project这个命令会检查publish.workspaceDir指定的目录是否存在。如果不存在，它会尝试初始化一个新的 Quartz 项目。如果目录已存在但可能包含其他内容，为了安全，它默认不会执行可能覆盖文件的操作。如果你确认该目录可以初始化，需要显式设置环境变量：
ALLOW_DESTRUCTIVE=1 node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js setup-project3. 同步笔记内容将 Obsidian Vault 中指定文件夹的内容，同步到 Quartz 项目的content目录下。
node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js sync这是内容流转的关键一步。根据你的publish.syncMode配置（mirror或append），技能会使用rsync进行文件复制。建议首次运行时，在config.json中明确设置"syncMode": "append"以避免误删。
4. 构建静态网站在 Quartz 工作区中执行构建命令，将 Markdown 转换为 HTML、CSS、JS 等静态资源。
node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js build此步骤内部会运行npx quartz build。构建完成后，静态文件会输出到 Quartz 工作区的public文件夹中。同时，技能会执行一些后处理定制，如替换网站标题、注入“复制链接”按钮等。
5. 部署到 Cloudflare Pages将构建好的public目录部署到云端。
node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js deploy此步骤调用wrangler pages deploy命令，并使用你在.env中配置的凭证进行身份验证。部署成功后，Wrangler 会给你一个*.pages.dev的临时预览域名。
6. 一键执行完整流程当然，最方便的是使用run命令，它按顺序执行上述setup-project->doctor->sync->build->deploy所有步骤。
node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js run3.4 绑定自定义域名
使用*.pages.dev域名只是开始，绑定自己的域名才是最终目标。
- 在 Cloudflare 仪表板中，进入Workers & Pages。
- 找到你的 Pages 项目（项目名由
cloudflare.projectName配置）并点击进入。 - 在项目详情页，切换到自定义域标签页。
- 点击添加自定义域，输入你的完整域名（如
notes.yourdomain.com）。 - Cloudflare 会自动尝试配置 DNS 记录。你需要确保该域名的 DNS 是在 Cloudflare 管理的，这样它才能自动添加
CNAME记录指向你的 Pages 项目。如果域名不在 Cloudflare，你需要手动在你域名的 DNS 提供商处添加一条CNAME记录，指向你的*.pages.dev域名。 - 等待 DNS 传播（通常几分钟到几十分钟），然后就可以通过你的自定义域名访问网站了。
4. 配置详解与高级定制
4.1 配置文件深度解析
config.json是这个技能的大脑。理解每个字段，能让你灵活地控制发布行为。以下是一个带详细注释的配置示例：
{ "source": { // 【必填】你的 Obsidian 仓库的绝对路径 "vaultPath": "/Users/david/Documents/MyObsidianVault", // 【必填】需要发布的文件夹列表。只会同步这些文件夹下的内容。 "includeFolders": ["Clippings", "PublicBlog"], // 【可选】需要排除的文件夹列表。即使在 includeFolders 里，也会被忽略。 // 强烈建议排除 `.obsidian`（配置文件夹）和私人笔记文件夹。 "excludeFolders": [".obsidian", "Private", "Journal", "Templates"], // 【可选】是否要求笔记必须包含特定的 Frontmatter 才发布？ // 例如，设置为 true 并配合 Quartz 插件，可只发布有 `publish: true` 标签的笔记。 "requireFrontmatterPublish": false }, "publish": { // 【必填】Quartz 项目的工作目录。构建和部署都在这里进行。 "workspaceDir": "/Users/david/projects/my-quartz-site", // 【可选】Quartz 项目内用于存放同步内容的目录，默认为 "content" "contentDir": "content", // 【重要】同步模式。"mirror" 会删除目标目录中源目录没有的文件。 // "append" 只增不减，更安全。首次使用建议 "append"。 "syncMode": "append" }, "site": { // 静态网站生成器，目前固定为 "quartz" "generator": "quartz", // 网站标题，会显示在浏览器标签页和页面头部 "title": "David's Digital Garden", // 【重要】网站的最终访问地址，必须与 Cloudflare 中配置的自定义域名一致 "baseUrl": "https://notes.yourdomain.com", // Quartz 主题，可选 "default", "dark" 等，取决于你的 Quartz 配置 "theme": "default", // 是否在页面底部显示“反向链接”板块 "showBacklinks": true }, "cloudflare": { // 【必填】Cloudflare Pages 上的项目名称 "projectName": "my-obsidian-pages", // 【必填】部署到的分支，通常为 "main" 或 "production" "branch": "main", // 【必填】生产环境域名，与 site.baseUrl 对应 "productionDomain": "notes.yourdomain.com", // 【重要】指向 .env 文件中存储 API Token 的变量名 "apiTokenEnv": "CLOUDFLARE_API_TOKEN", // 【重要】指向 .env 文件中存储 Account ID 的变量名 "accountIdEnv": "CLOUDFLARE_ACCOUNT_ID", "basicAuth": { // 是否对整个网站启用 HTTP Basic 认证 "enabled": false, // 如果启用，用户名。建议从环境变量读取：`process.env.BASIC_AUTH_USERNAME` "username": "", // 如果启用，密码。建议从环境变量读取：`process.env.BASIC_AUTH_PASSWORD` "password": "" } } }4.2 自定义 Quartz 配置与主题
技能初始化的工作区是一个标准的 Quartz 项目。这意味着你可以完全控制 Quartz 的配置和外观。
1. 修改 Quartz 配置进入publish.workspaceDir指定的目录，你会看到quartz.config.ts或quartz.config.js等文件。你可以在这里：
- 调整解析器、插件和过滤器，以改变内容处理逻辑。
- 修改导航栏、页脚等布局组件。
- 例如，你可以安装
quartz-plugin-tag-pages来生成标签云页面。
2. 自定义样式主题Quartz 使用typography.css等文件定义样式。你可以直接修改这些 CSS 文件，或者更优雅地，通过覆盖 CSS 变量来定制主题。查看 Quartz 文档了解如何创建自定义主题。
3. 技能后处理的影响需要注意的是，本技能在构建后会对生成的 HTML 进行一些后处理（如替换标题、添加复制按钮）。这些修改是直接作用于输出文件的。如果你发现自己的主题修改被覆盖了，可能需要检查技能的后处理脚本（通常在skills/obsidian-cloudflare-pages/lib/post-build.js或类似位置），并调整其逻辑或顺序。
4.3 实现增量发布与自动化
手动运行run命令固然可以，但结合 Git 和 CI/CD 可以实现真正的自动化。
1. 将 Quartz 工作区纳入 Git 管理
cd /path/to/your/workspaceDir git init git add . git commit -m "Initial quartz project"将代码仓库（例如 GitHub）设置为远程仓库。
2. 创建自动化脚本你可以创建一个简单的 Shell 脚本，例如deploy.sh：
#!/bin/bash cd ~/.openclaw/workspace # 安全起见，先同步和构建，但不部署 node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js sync node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js build # 检查是否有内容变更 cd /path/to/your/workspaceDir if git diff --quiet --exit-code public/; then echo "No changes to deploy." else echo "Changes detected, deploying..." # 提交变更 git add public/ git commit -m "Auto-update site content" git push origin main # 执行部署 cd ~/.openclaw/workspace node skills/obsidian-cloudflare-pages/bin/publishmd-cf.js deploy fi然后通过系统的定时任务（如cron）来定期执行这个脚本，实现定时发布。
3. 使用 GitHub Actions 实现 Git 触发更现代的做法是，当你向 Obsidian Vault 的特定文件夹（如Clippings）推送更改时，触发一个 GitHub Action。这个 Action 可以在云端执行技能的run命令。这需要将你的技能配置、环境变量（作为 GitHub Secrets）和 Obsidian Vault（或至少发布文件夹）都放在 Git 仓库中。设置相对复杂，但实现了完全无缝的“写笔记即发布”。
5. 故障排查与经验心得
5.1 常见问题与解决方案
在实际使用中，你可能会遇到以下问题。这里记录了我的排查思路和解决方法。
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
运行doctor或任何命令时报错Command failed | 1. 依赖未安装 (Node, rsync, wrangler)。 2. 路径配置错误。 3. 权限不足。 | 1. 根据错误信息，确认node,npm,rsync,wrangler是否在系统 PATH 中且版本兼容。2. 检查 config.json中的source.vaultPath和publish.workspaceDir是否为绝对路径且存在。3. 确保对相关目录有读写权限。 |
sync命令成功但content目录为空 | 1.includeFolders配置的文件夹在 Vault 中不存在或为空。2. excludeFolders意外排除了目标文件夹。3. rsync命令参数或路径有误。 | 1. 仔细核对includeFolders的名称，确保大小写一致。2. 临时将 excludeFolders设为空数组[]测试。3. 使用 --dry-run参数运行sync命令，查看rsync实际会执行的操作：node .../publishmd-cf.js sync --dry-run。 |
build命令失败，Quartz 报错 | 1. Quartz 项目未正确初始化或损坏。 2. 同步过来的 Markdown 文件语法有误（如 Frontmatter 格式错误）。 3. Node 版本不兼容。 | 1. 尝试删除workspaceDir目录，然后重新运行ALLOW_DESTRUCTIVE=1 node .../publishmd-cf.js setup-project。2. 查看 Quartz 构建的错误日志，定位到具体文件。常见问题是笔记中有不合规的 YAML Frontmatter。 3. 确保使用 Quartz 4 推荐的 Node.js 版本（如 LTS 版本）。 |
deploy失败，提示认证错误 | 1..env文件未创建或路径不对。2. .env文件中的CLOUDFLARE_API_TOKEN或CLOUDFLARE_ACCOUNT_ID无效或过期。3. Token 权限不足。 | 1. 确认.env文件位于skills/obsidian-cloudflare-pages/目录下，且内容格式正确（无多余空格，每行KEY=VALUE）。2. 在 Cloudflare 面板重新生成 API Token 并更新 .env文件。确保 Account ID 正确。3. 确认 Token 模板包含“编辑 Cloudflare Pages”权限。 |
| 网站能访问，但样式丢失或页面错乱 | 1.site.baseUrl配置错误。2. Cloudflare Pages 项目构建输出目录设置错误。 3. 自定义域名 DNS 未正确解析或 HTTPS 证书未就绪。 | 1. 检查config.json中的site.baseUrl是否与 Cloudflare 中配置的生产域名完全一致（包括https://）。2. 在 Cloudflare Pages 项目设置中，确认“构建输出目录”是否为 public。3. 访问 *.pages.dev临时域名看是否正常。如果正常，问题在域名解析，等待 DNS 生效或检查 CNAME 记录。 |
| Basic Auth 不生效 | 1.cloudflare.basicAuth.enabled为false。2. 用户名密码错误。 3. Cloudflare Pages 的 Functions 功能未启用或中间件生成失败。 | 1. 确认配置已启用，且用户名密码已正确设置（或在.env中配置）。2. 部署后，检查项目 functions目录下是否生成了_middleware.js文件。3. 在 Cloudflare Pages 控制台查看部署日志，确认 Functions 已成功部署。 |
5.2 实操中的经验与避坑指南
1. 关于syncMode: mirror的谨慎使用mirror模式非常高效，能确保 Quartz 的content目录是你 Vault 指定文件夹的精确副本。但这把“双刃剑”意味着，如果你在content目录里手动添加或修改了文件（而非通过 Obsidian），下次同步时这些文件会被无情删除。我的建议是：除非你完全理解并需要这种严格同步，否则始终使用append模式。或者，在运行sync前，先使用--dry-run参数预览将要删除的文件列表。
2. 处理 Obsidian 特有的语法Obsidian 允许一些非标准的 Markdown 语法，如![[内部嵌入]]、^^高亮^^等。Quartz 可能无法直接解析它们。你需要：
- 要么在 Obsidian 中写作时，尽量使用标准 CommonMark 或 GitHub Flavored Markdown 语法。
- 要么探索 Quartz 社区插件，或者自己编写转换器，在
sync之后、build之前，将 Obsidian 语法转换为 Quartz 能理解的格式。这可以作为技能的一个扩展点。
3. 管理大量笔记时的构建性能如果你的 Vault 里有成千上万篇笔记，即使只发布其中一部分，Quartz 的构建时间也可能变长。可以考虑：
- 增量构建：Quartz 本身支持基于 Git 的增量构建。你可以将 Quartz 工作区初始化为 Git 仓库，并确保
sync过程能生成有意义的 Git 提交，这样 Quartz 在构建时可能只处理更改的文件。但这需要更精细的流程控制。 - 拆分发布：不要试图一次性发布整个知识库。用
includeFolders将内容分门别类，建立多个不同的发布项目（如“技术笔记站”、“读书摘录站”），每个站点只包含相关文件夹。
4. 备份你的配置和.env文件config.json和.env是你整个发布流程的命脉。务必将其备份到安全的地方（如使用密码管理器保存.env内容，将config.json存入私有 Git 仓库）。一旦丢失，重新配置会非常麻烦。
5. 善用SAFE_MODE和--dry-run这是本技能设计中最值得称道的安全特性。在尝试任何新操作、修改关键配置后，或者只是定期执行脚本前，先加上SAFE_MODE=1或--dry-run跑一遍。它能让你清晰地看到工具将要做什么，而不会产生任何实际影响。养成这个习惯，能避免绝大多数灾难性误操作。
这个obsidian-cloudflare-pages-skill将 Obsidian 的内容价值从本地释放到了网络，其设计在自动化与安全性之间取得了很好的平衡。从我自己的使用体验来看，最大的收获不是技术本身，而是它促成了一种“发布即整理”的笔记习惯——知道笔记可能会被公开，反而促使我写得更清晰、结构更完整。如果你也受困于笔记的“沉睡”状态，不妨用这个工具，迈出构建个人数字花园的第一步。
