开源自用的博客系统notion-fuwari

先说目标：这套博客解决什么问题#

我希望它解决的不是“能不能发一篇文章”，而是下面这几个长期问题：

• 写作和发布流程太割裂
• 图片管理容易混乱
• 中文站做英文内容时容易出现路由和 SEO 混乱
• 内容多了以后检索和归档体验下降

所以这个项目从一开始就不是纯主题皮肤，而是一个可长期维护的博客基座。

功能总览#

目前这一版的能力可以分成 6 组：

1. 内容生产链路：Notion 同步 + Markdown 内容体系
2. 资源管理链路：图片自动下载、本地化、按文章归档
3. 阅读与导航：搜索、归档、标签、图书模块、移动端适配
4. 双语能力：中英双路由、译文互跳、语言维度列表
5. SEO 能力：canonical、hreflang、结构化数据、RSS、sitemap
6. 运营能力：统计、评论、友链申请与审核、可选 AI 问答

下面按链路拆开说。

1) 内容生产链路：以 Notion 为主阵地#

核心思路是“在 Notion 写，在博客发布”。

• 通过脚本把已发布内容同步到 src/content/posts
• frontmatter 自动带出发布时间、标签、描述等元信息
• 可以选择覆盖同步或仅新增同步，适配不同工作流

这带来的好处是明显的：

• 写作环境统一，协作也更容易
• 发布流程可脚本化，减少手动错误
• 内容在仓库里依旧是纯 Markdown，可审计、可回滚
• 纯自动化流程同步文章，要做的只需要在notion上写文章即可

2) 图片资源链路：自动下载 + 本地化引用#

这是很多博客项目最容易被忽略的一段，但实际非常关键。

当前实现里，文章图片会被自动拉到本地并按文章分类存放，避免“外链图床失效导致历史文章坏图”的问题。同步后正文里的链接也会替换成本地路径。

对长期写作来说，这个能力的价值很高：

• 文章可迁移，不依赖第三方图床稳定性
• 图片目录结构清晰，后期维护成本低
• 构建与部署时更可控

3) 阅读体验：不只是一页文章#

博客不仅是“单篇阅读”，还包括“找得到、回得去、能持续读”。

这里主要做了这些：

• 首页分页和文章卡片
• 归档页和标签页
• 全文搜索
• 图书模块（适合长篇章节内容）
• 响应式布局（桌面与移动端一致性）

尤其是图书模块，对教程、翻译、系列化内容很友好，比把长文硬塞进单页更可维护。

4) 双语能力：中英路由、互跳、列表隔离#

这一块是最近重点打磨过的能力，目标是“对用户清晰，对搜索引擎也清晰”。

已经实现的规范包括：

• 中文默认路由：/posts//
• 英文前缀路由：/posts/en//
• 每篇文章带 lang 与 translationKey
• 切换语言时按 translationKey 精确跳转对应译文
• 首页、归档、标签、搜索按语言展示，不混杂

还有一个很重要的点：不做自动语言重定向，避免短暂跳转影响体验和广告平台风控判断。语言切换由用户主动触发。

5) SEO 能力：从“可被收录”到“可被正确理解”#

这里不只做 meta 标签，而是把语言和 URL 体系打通。

目前站内关键页面都支持：

• canonical 指向当前语言规范 URL
• hreflang（zh-CN / en / x-default）
• 页面语言与结构化数据语言一致
• 自动生成 RSS 与 sitemap

同时，about / friends / sponsors 也已经补齐英文路由与 hreflang，英文入口完整性更好。

6) 运营能力：写完之后还能持续迭代#

项目里还做了几块偏运营的能力：

• 访问统计（Umami）
• 评论系统接入
• 友链申请 + Notion 审核 + 同步展示
• 可选 AI 问答入口（基于站内内容检索，由cf大善人买单！）

它们不直接影响“能不能发文”，但会明显影响“站点能不能长期运营”。

技术栈简述#

核心技术栈大致是：

• Astro（静态站点主框架）
• Tailwind CSS（样式体系）
• Svelte（部分交互组件）
• Notion API + 同步脚本（内容链路）
• 一组围绕内容查询、URL 生成、SEO 生成的实用层

总体原则是“以静态为主，脚本化增强内容生产和运维能力”。

如果你也想用这套方案#

可以直接从仓库开始看：

https://github.com/evepupil/notion-fuwari

建议阅读顺序：

1. README 先了解整体能力边界
2. src/content 看内容模型和目录约定
3. scripts 看 Notion 同步与迁移脚本
4. src/pages + src/utils 看路由和 SEO 规则

最后#

我做这个项目的初衷很简单：把“写作、发布、检索、双语、SEO、运营”连成一条稳定链路。

如果你也在做一个长期写作的技术博客，希望这套实现能给你一点可复用的参考。