31 October 2026, 15:30 (GMT+8)

2026年10月31日 15:30（东八区 / 北京时间）

Ametrine 主题预开发解耦 · Bilibili / 网易云组件 · 主题化构建与 CI 重构

概述

今天的工作集中在 主题开发流程解耦、媒体嵌入组件和构建链路统一：

将官方 ametrine 与个人预开发主题 ametrine-pre 拆成两个独立子模块，个人特性先在预开发仓库演进，再把可独立评审的功能提交给上游；
在预开发主题中新增 Bilibili 和网易云音乐两个 iframe 播放器组件，同时支持短代码调用与官方 iframe 源码直接粘贴；
让站点根据 zola.toml 的 theme 自动同步 Sass、模板和语法高亮资源路径，避免手工替换 ametrine / ametrine-pre；
合并 dev.sh 与 build-site.sh，统一为 build-site.sh build|serve；
重构 GitHub Actions，删除硬编码主题克隆，只初始化当前实际使用的主题及递归依赖。

本地完整流水已通过隔离验证；当前改动尚未完成线上部署验证。

一、主题预开发与上游仓库解耦

1.1 双主题结构

00BlogZola 现在保留两个主题子模块：

目录	用途
`themes/ametrine`	官方上游主题，保持可追踪更新
`themes/ametrine-pre`	个人预开发主题，用于试验、定制和收集未来可上报的特性

当前站点使用的主题为：

theme = "ametrine-pre"

ametrine-pre 当前 HEAD：

20ad42b Support embedding NetEase Cloud Music

1.2 功能提交拆分

预开发主题中包含两类修改：

目录兼容修改：适配 themes/ametrine-pre 的图标、i18n、数据和组件加载路径；
可上游功能：Bilibili、网易云音乐等与目录无关、可单独评审的组件。

上游候选分支严格基于官方基线，只保留功能相关文件，避免把个人目录适配和完整预开发历史一起带入上游 PR。

二、媒体播放器组件

2.1 Bilibili

新增 templates/components/bilibili.html，支持以下参数：

参数	默认值	说明
`id`	必填	BVID，也兼容 `av` 号
`page`	`1`	分 P
`high_quality`	`true`	请求平台允许的高画质
`danmaku`	`false`	是否显示弹幕
`as_wide`	`true`	宽屏布局
`autoplay`	`false`	自动播放
`start`	`0`	起始秒数
`poster`	`false`	播放前显示封面

调用方式：

{{ <bilibili id="BV1VDtk6jEpa"/> }}

同时支持把 Bilibili 官方分享框中的 iframe 源码直接粘贴到 Markdown，CSS 会自动识别 player.bilibili.com 并应用 16:9 布局。

2.2 网易云音乐

新增 templates/components/netease_music.html：

参数	默认值	说明
`id`	必填	数字歌曲 ID
`autoplay`	`false`	是否尝试自动播放

调用方式：

{{ <netease_music id="3443840079"/> }}

官方外链播放器源码也可以直接粘贴：

<iframe
  frameborder="no"
  border="0"
  marginwidth="0"
  marginheight="0"
  width=369
  height=86
  src="//music.163.com/outchain/player?type=2&id=3443840079&auto=0&height=66">
</iframe>

组件统一约束为 369 × 86px 的响应式尺寸，并补充 autoplay、encrypted-media 权限和可访问标题。CSP 同时加入 music.163.com。

2.3 网易云歌词能力调查

检查当前官方 outchain/player 的 HTML、CSS 和加载脚本后确认：

外链播放器只有小型、中型、封面和列表等布局；
参数仅涉及 type、id、auto、height、bg；
没有歌词参数，也没有向父页面暴露播放时间；
网易云歌词数据虽然可以通过独立 API 获取，但无法与跨域 iframe 内的播放进度可靠同步。

因此当前组件明确只负责播放，不伪装成支持在线歌词。相关限制已写入主题 demo 文档。

三、主题路径自动同步

3.1 问题

站点 Sass 中存在大量类似路径：

@use "../../themes/ametrine-pre/sass/citrine/sass/abstracts/functions" as *;

主题模板覆盖也使用：

{% extends "ametrine-pre/templates/base.html" %}

直接切换 theme 时，这两类路径不会自动变化。

Sass 的 @use 不能读取 Zola 运行时配置，Tera 的 extends 又要求字符串字面量，因此无法在模板或 SCSS 中直接写成 config.theme 变量。

3.2 构建前同步

新增 scripts/sync-theme.mjs：

从 zola.toml 读取唯一的字符串 theme；
校验主题名和 themes/<theme> 目录；
同步 sass/ 中的 themes/<name>/sass/...；
同步 templates/ 中的 extends "<name>/templates/..."；
同步 extra_themes 中使用的主题资源路径；
支持 --check 只检查、--print-theme 供 CI 读取主题名。

当前 ametrine-pre 下的 Sass、模板和高亮资源路径均已对齐同一主题。

四、构建入口统一

dev.sh 和 build-site.sh 原本重复执行主题/密文同步，只差最后的 zola serve 与 zola build。现已删除 dev.sh，只保留统一入口：

./build-site.sh                         # 默认正式构建
./build-site.sh build --output-dir ...  # 显式构建
./build-site.sh serve                   # 本地开发
./build-site.sh serve --open
./build-site.sh serve -p 3000

统一流程：

sync-theme
→ encrypt-content
→ fetch-repo-commits
→ zola build / zola serve
→ post-build
→ verify-kanban-build

serve 模式不执行构建后处理和部署校验，保留本地热重载体验。

五、CI 重构

原 workflow 中存在以下问题：

硬编码 git clone .../ametrine.git themes/ametrine，与当前 theme = "ametrine-pre" 不一致；
显式克隆会绕过父仓库固定的子模块提交；
初始化所有主题，浪费时间和带宽；
构建脚本与 workflow 各自重复执行看板校验；
下载、主题初始化和部署步骤缺少完整 fail-fast；
重复触发时可能并发覆盖 gh-pages；
无内容变化时仍可能产生无意义提交。

deploy_pages.yml 现在会：

THEME="$(node scripts/sync-theme.mjs --print-theme)"

git submodule sync --recursive -- "themes/$THEME"
git submodule update --init --recursive -- "themes/$THEME"

./build-site.sh --output-dir ../public_html

主题源码仍然必须拉取，因为模板、Sass、图标和 Citrine 都位于主题子模块中；但不再手动克隆，也不会拉取当前未使用的主题。

同时增加了：

set -euo pipefail；
Zola 下载重试；
当前主题类型与目录校验；
gh-pages 发布并发控制；
20 分钟 job 超时；
输出文件检查；
无变化时不创建部署提交。

六、验证

已通过：

shellcheck build-site.sh；
bash -n build-site.sh；
node --check scripts/sync-theme.mjs；
node scripts/sync-theme.mjs --check；
Workflow YAML 语法检查；
只初始化当前主题的递归子模块命令；
隔离环境完整流水：
- 307 个 HTML 页面；
- 网易云两条 CSS 选择器；
- 18 个 feed 的后处理通过；
- 6 个 Kanban 周页校验通过。

推送前仍需修复 content/design/index.md 中一处 TOML 表项缺少逗号的问题；隔离流水使用该文件的已提交版本完成验证。

七、当前状态

ametrine-pre 本地与远端 main 均为 20ad42b；
Bilibili 功能已整理并提交上游 PR；
网易云功能已拆成只包含组件、样式、文档和 CSP 的独立上游候选提交；
主题路径同步、统一构建脚本与 CI 改动已完成本地验证；
Actions 仍使用手动 workflow_dispatch，Codeberg 推送本身不会自动触发 GitHub 部署；
线上 gh-pages 尚未进行本轮最终验证。

八、构建前自动同步 `updated` 日期

在 build-site.sh 中加入 sync_updated_dates() 函数。它会在主题同步、内容加密、仓库数据抓取和 Zola 构建/预览之前，扫描 content/**/index.md，确保 front matter 中的 updated 始终为 yyyy-mm-dd 格式。

日期来源不是简单取当前时间：

已提交且除 updated 外没有其他修改的文件，使用 Git 最后提交日期；
本地有真实未提交修改、或者文件尚未纳入 Git 的文件，使用文件系统最后修改时间；
只有 updated 被自动改动时，继续使用 Git 提交日期，保证函数可重复执行；
缺少 updated 时自动插入；有 date 字段时放在它后面；
只修改文件顶部的 TOML front matter，不触碰正文；
front matter 不合法时直接报错，阻止后续构建。

当前执行结果：

扫描 index.md：91
有效 updated：91
缺失：0
日期不一致：0

函数连续执行两次后，第二次输出为：

updated: 0 file(s) synchronized, 91 unchanged

build 与 serve 两种模式都会在启动 Zola 前执行该函数；函数内部逻辑、日期优先级、幂等处理和错误行为均已加入代码注释。

相关链接：预开发主题 · Nanolog 列表 · 站点首页

20 October 2026, 20:00 (GMT+8)