三次 build 环境问题实录：Turbopack 持久缓存重放旧失败、孤儿进程占端口假回归、CRLF 行尾导致 frontmatter 未剥离。附排查顺序。

从 jiusi-notes 的 v3.25.0 重构讲起：为什么把站点配置与 Markdown 内容彻底分离，配置驱动元数据的加载器如何设计，以及这中间踩过的坑。

为什么内容型技术博客选 Next.js 全家桶而不选 MDX 官方方案；静态与动态混合渲染的分区策略；自研 Markdown 管线的动机。

语义 token 单源、浅暗双套、@theme inline 映射、第三方组件色一致。以及 BARE-VAR 陷阱：为什么 bg-[--var]/N 在暗色下失效。

SSG+ISR 下的 canonical/OG/sitemap/RSS 配置，一个"每页 canonical 都指向首页"的重复内容坑，以及中文 slug 的三个注意点。

内容站"带病上线"的三种静默故障，preflight-check.mjs 的 5 步校验设计，--fix 自动补全默认字段，以及 deploy.sh 一键发布的安全设计。

版本号三处同步、内容与代码分离后的维护边界、写作发布工作流、让站点三年后还能改的工程习惯。

不用数据库、纯文件存储的评论系统怎么保证并发安全。进程内锁 + 原子写 + 超时自愈 + AC 自动机敏感词过滤，附完整设计。

jiusi-notes 弃用 @next/mdx，自研 755 行 Markdown 渲染器。讲 XSS 转义范式、KaTeX/Mermaid 接入、TOC 一致性与四个"看着对实际错"的坑。

node_modules 永不拷上传、Apache 反代 Node、pm2 管理、自动重建脚本。以及"本地好好的线上 404"的真相。