therainisme.com 静态化记录
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 是触发时间,不是发布完成时间。新内容的上线时间取决于构建排队、内容获取和部署耗时。
需要立即发布时,可以手动触发构建。无论由代码推送、定时任务还是手动操作启动,最终执行的都是同一套内容获取和静态生成过程。