therainisme.com 静态化记录

TagsTutorial
Publication DateNovember 15, 2026

therainisme.com 改成了静态网站。Notion 保存内容,构建脚本生成页面,Cloudflare 提供访问。

这次调整把内容获取和页面渲染放到了构建阶段。访问者拿到的是已经生成好的 HTML,不需要等待 Notion 返回数据。

内容在什么时候变成网页

使用 Notion 作为内容来源,不一定要在每次访问时调用 Notion API。

文章正文、照片和导航通常不会随访问者变化。同一篇文章可以提前生成一次,供后续访问重复使用。

网站现在分为两个阶段:

  • 构建阶段:读取 Notion,转换内容,生成文件
  • 访问阶段:根据网址返回对应的静态文件

构建脚本承担了原本可能发生在访问时的数据获取和页面生成工作。Cloudflare Worker 只负责提供静态资源,不在请求过程中读取 Notion。

Notion 的响应速度会影响构建耗时,不影响已发布页面的读取。Notion 暂时不可用时,新内容的构建可能失败,已经部署的页面仍可访问。

代价是更新存在延迟。Notion 中的修改需要经过一次成功的构建和部署,才会出现在网站上。

从 Notion 获取内容

Notion API 返回的不是完整网页,而是页面属性和内容块。

标题、段落、列表、图片都属于不同类型的块。一些块还包含子块,需要继续读取。页面较长时,API 会分页返回结果,脚本需要使用游标获取后续内容。

获取过程可以简化成下面的伪代码:

function fetchBlocks(pageId):
    blocks = []
    cursor = null

    repeat:
        result = requestBlocks(pageId, cursor)
        blocks.appendAll(result.items)
        cursor = result.nextCursor
    until cursor is null

    for block in blocks:
        if block.hasChildren:
            block.children = fetchBlocks(block.id)

    return blocks

一次构建往往需要多次 API 请求。请求过快会遇到限流,网络和服务端也可能出现临时错误。

scripts/notion.mjs 负责控制请求频率,并对限流和部分服务端错误重试。重试不能解决所有问题,但可以减少短暂故障造成的构建失败。

这一阶段只负责取得内容,不处理页面样式。

把内容块转换成 HTML

scripts/render.mjs 负责将 Notion 的内容结构转换成 HTML。

不同类型的块对应不同的 HTML 元素。段落对应 p,标题对应不同级别的标题元素,列表需要组合成列表结构。文字内部的加粗、链接和行内代码也需要单独处理。

渲染逻辑可以简化为:

function render(block):
    switch block.type:
        case paragraph:
            return element("p", renderRichText(block.text))
        case heading:
            return element(headingTag(block.level), renderRichText(block.text))
        case image:
            return renderImage(block)
        case equation:
            return renderKatex(block.expression)

这里的 renderRichText 不只是拼接字符串。普通文本需要 HTML 转义,避免正文中的 <、> 等字符被浏览器当作标签。文字样式和链接再转换成对应的标记。

公式使用 KaTeX 在构建时渲染。浏览器收到页面时,公式结构已经存在,不需要再加载脚本执行一次公式转换。

文章正文被直接写进 HTML。浏览器不需要先运行 JavaScript,再请求文章数据。

页面与资源

内容块生成的 HTML 还不是完整页面。

scripts/build.mjs 把正文放进页面模板,加入导航、标题、描述和样式引用,再写入输出目录。

构建过程可以概括为:

clearDirectory("dist")

pages = fetchNotionPages()

for page in pages:
    blocks = fetchBlocks(page.id)
    body = renderBlocks(blocks)
    html = renderPage(page.metadata, body)
    writePage(page.path, html)

writeSiteFiles(pages)

以上伪代码省略了资源下载、错误处理等细节,只保留主要步骤。

每次构建前清空 dist,避免已经删除或改名的页面残留在输出目录。新的输出只包含本次构建生成的文件。

图片在构建阶段处理,页面引用发布后的站点资源。字体也由站点托管,减少页面展示对外部服务的依赖。

这些资源会随网站一起部署。Notion 负责提供源内容,访问者不需要通过 Notion 加载正文和图片。

页面结构

导航保留四项:

  • Home:首页和文章列表
  • Friends:朋友们的网站
  • Memory:照片
  • Tools:工具

Friends 使用独立页面,保留简单轮播。Memory 使用照片网格,桌面端五列,手机端两列。

网站没有引入前端框架。正文和布局由 HTML、CSS 完成,运行时的 JavaScript 主要用于 Friends 轮播。

静态页面也可以有交互。轮播只需要操作页面中已有的内容,不需要重新获取整页数据,也不需要把网站做成一个前端应用。

视觉上保留接近 Notion 的排版,调整字体、留白和移动端布局。404 页面只保留提示和返回入口。

页面之外的文件

构建脚本使用同一份页面数据生成 sitemap 和 RSS。

sitemap 列出站点页面,供搜索引擎发现内容。RSS 提供文章订阅,不要求读者定期打开首页查看更新。

每篇文章生成独立的页面标题和描述。canonical 标明页面的规范地址,robots.txt 声明抓取规则。

这些文件和正文在同一次构建中生成,避免文章已经更新,订阅和页面清单仍停留在旧版本。

部署与定时更新

部署使用 Cloudflare Workers Builds,不再使用 GitHub Actions。

代码推送到 main 分支后,Cloudflare 执行检查、构建和部署。构建会重新读取 Notion,发布的版本同时包含仓库代码和当时获取到的内容。

Notion 内容更新不会产生 Git 提交,网站另外保留了每日重建。

北京时间每天 04:00,现有的 scheduler Worker 向部署挂钩发送一次 POST 请求。挂钩通知 Cloudflare 启动构建。

定时任务不负责获取文章,也不直接修改线上文件。它只负责发出构建请求,后续仍由同一条流水线完成。

Cloudflare 的 cron 按 UTC 解析。北京时间 04:00 对应前一天 UTC 20:00,表达式为 0 20 * * *。

04:00 是触发时间,不是发布完成时间。新内容的上线时间取决于构建排队、内容获取和部署耗时。

需要立即发布时,可以手动触发构建。无论由代码推送、定时任务还是手动操作启动,最终执行的都是同一套内容获取和静态生成过程。