AstroPaper 博客改造日志

基于 AstroPaper 模板搭建了这个博客。AstroPaper 是一个极简、响应式、无障碍友好的 Astro 博客主题，支持亮暗模式切换，自带文章系统、标签、归档、搜索、RSS 等功能。

这篇日志持续记录对它的改动，会随提交不断更新。

2026-05-21 — 中文本地化

新建中文翻译文件 src/i18n/lang/zh.ts，逐条翻译了导航、文章页、分页、首页、页脚、404 等所有 UI 文案，默认语言切换为 zh。

日期格式方面，引入 dayjs 中文 locale，改为 2025年3月22日 周六 的形式。

删除了 _releases（版本发布记录）和 _color-schemes（颜色方案文档）两个目录及其图片资源。额外清理了 about 页面和依赖更新文章中的示例图片引用。

新增了一篇 Markdown 功能测试文章，验证中英文混排效果。.gitignore 加入 .claude 目录。

2026-05-22 — 首页与归档布局

首页大删减：去掉了 hero 区域的介绍段落、RSS 图标、社交链接。不再区分”精选文章”和”最近文章”，直接展示最新 N 篇文章流，底部保留”全部文章”链接按钮。打开即见文章列表。

归档页从完整 Card 改为紧凑展示。Card 组件新增 compact 变体——单行，左侧 MM-DD 日期，右侧标题。顺手修了首篇文章与月份标签未对齐的问题。

同日下午修复了 Datetime 组件中的冗余日期格式化代码。

2026-05-25 — 移除分享组件

删除了文章页的”分享这篇文章”功能——Twitter/Facebook 等平台在国内基本不用，浏览器自带复制链接足够了。

具体清理：删除 ShareLinks.astro 组件及其在文章页的引用，移除 astro-paper.config.ts 和类型定义中的 shareLinks 配置，删除 i18n 中 sharePostIntro 等翻译键，清理 facebook、telegram、pinterest、whatsapp 四个纯分享用途的 SVG 图标。

顺手把 zh.ts 中页脚的”版权所有 保留所有权利”改回英文 Copyright / All rights reserved.——中文法律措辞放在个人博客上太突兀。

2026-05-25 — 精简社交链接

页脚社交图标从 4 个（GitHub、X、LinkedIn、邮箱）精简为 2 个，去掉国内基本不用的 X 和 LinkedIn，只保留 GitHub 和邮箱，并替换为实际地址：

• GitHub: https://github.com/kingstar718
• 邮箱: kingstar718@foxmail.com

配置文件从 astro-paper.config.ts 的 socials 数组中移除对应条目即可，组件层面自动适配。

2026-05-25 — 配置修正与内容清理

修正了两项残留的模板配置：

• profile 链接从 https://satna.ing 改为 https://github.com/kingstar718
• editPost.url 从 satnaing/astro-paper 改为 kingstar718/astro-paper-blog

About 页面从英文模板介绍重写为简短的个人标识：「陆上江南的博客」。

examples/ 目录下 4 篇英文示例文章和根级 3 篇模板指导文章（adding-new-post、customizing-astropaper-theme-color-schemes、how-to-configure-astropaper-theme）全部设为草稿（draft: true），不再公开显示，但保留原文件以备后续参考。

2026-05-25 — 修复本地编译

本地编译一度因为构建阶段需要访问外部资源而失败。为缩短构建链路，关闭了动态 OG 图片：features.dynamicOgImage 设为 false，改用已有的静态默认图片，并删除相关图片生成路由和工具函数。

顺手清理：Datetime.astro 中删除未使用的 useTranslations 导入和 t 变量，编译从 1 hint 变为 0 hints。

最终编译结果：0 errors / 0 warnings / 0 hints，23 个页面正常生成。

2026-05-30 — 文章页脚本幂等化

继续清理文章页的客户端脚本。之前的实现每次进入文章页都会重新创建阅读进度条、重新给标题追加 # 锚点、重新包裹代码块并插入复制按钮；在启用 Astro 客户端路由后，来回切页时有重复插入 DOM 和重复绑定事件的风险。

这次把脚本改成“可重复执行但结果不重复”：

• 阅读进度条改为固定 ID，若已存在则复用
• 滚动监听和 astro:after-swap 监听在重新绑定前先移除旧实例
• 标题锚点仅在缺失时追加
• 代码块按钮仅在不存在时插入，外层包裹节点也只创建一次

顺手把代码块复制按钮文案从英文 Copy / Copied 改成中文 复制 / 已复制，和整站语言保持一致。

本地预览里来回切换文章页后复查，进度条、标题锚点和复制按钮数量都保持不变，说明这部分脚本已经稳定下来。

2026-05-30 — 模板文章下线

又做了一轮“减法”，主要目的是让公开内容和实际站点风格更一致。

先把还在公开状态的 5 篇 AstroPaper 模板文章全部改为草稿：动态 OG、依赖更新、Git Hooks 日期、Giscus 评论、LaTeX 公式。它们仍然保留在仓库里，后面需要参考时随时可翻，但不再出现在首页、文章列表、归档、RSS 和搜索结果中。

这样处理后，首页公开文章只剩真正属于当前博客的内容，站点气质会更统一，不会再混入一批模板作者的英文教程。

本轮调整后重新执行 pnpm build，astro check、静态构建和 Pagefind 索引生成均通过；公开页面数量从 23 页收缩到 14 页，搜索索引也随之只保留当前真正对外展示的文章内容。

2026-05-30 — 项目说明与内容目录收口

继续把仓库从“套了 AstroPaper 的模板项目”整理成真正属于这个博客的项目。

首先重写了 README.md。旧 README 仍然保留大量原模板说明，包括已经删除的默认 OG 图片、动态 OG 功能、原作者联系方式和模板初始化命令。新版本改为说明当前博客的定位、目录结构、常用命令、写作方式和配置入口，并明确部署时发布 dist/ 目录。

About 页面也从一句占位介绍扩展为真正的个人博客说明：这个站点写什么、为什么保留静态博客形态、以及读者能在这里看到哪些内容。

模板文章则整体移出正式内容目录：

src/content/posts/        # 只放正式博客文章
docs/templates/posts/     # 保留 AstroPaper 模板文章作为参考资料

这样 src/content/posts/ 里只剩公开内容，不再混着一堆草稿模板文件；日后查找、搜索和新增文章都会更清楚。

最后顺手修了构建脚本。以前 pnpm build 会在 Pagefind 索引生成后执行 cp -r dist/pagefind public/，把构建产物再写回源码目录。现在搜索索引只保留在 dist/pagefind/，部署 dist/ 即可，不再污染 public/。

搜索页开发态提示也改成中文。至此，模板尾巴又少了一截。

2026-05-30 — 清理测试内容与历史计划

继续清掉几处不再适合留在正式站点里的内容。

public/pagefind/ 是旧构建脚本留下的本地搜索索引，现在构建产物只保留在 dist/pagefind/，因此直接删除本地残留目录，避免把生成文件误认为源码资产。

docs/superpowers/ 里保存的是已经失效的早期改造计划。为了避免后续误读，删除了这些过期文档。

社交图标也继续精简：linkedin.svg 和 x.svg 已经没有实际配置引用，页脚只保留 GitHub 和邮箱，所以这两个图标文件一并移除。

最后把 Markdown 功能测试文章移出公开内容目录，放到 docs/testing/markdown-feature-test.md。它仍然可以作为排版回归测试参考，但不再作为博客文章公开展示。

字体系统演进

字体是这个博客改动次数最多的一部分。目标一直没有变：中文适合长篇阅读，英文和代码清晰，同时保证国内访问稳定、构建过程可靠、字体体积可控。

2026-05-21 — 从在线字体开始

最初通过 Astro 的字体能力加载 Noto Sans SC，随后因为更偏好中文衬线字体的阅读感，换成 Noto Serif SC。CJK 字库体积很大，构建阶段下载经常超时，因此又改为通过 Google Fonts CDN 加载。

这一阶段使用过 Google Sans Code 和 Noto Serif SC 的组合，但很快发现它存在两个问题：

• 国内网络访问 Google Fonts 不稳定
• 构建和运行依赖外部字体服务

2026-05-25 — 字体本地化

为了去掉外部依赖，字体开始转为本地托管。英文正文使用 Inter，代码使用 JetBrains Mono，中文使用本地 Noto Serif SC。

当时的字体栈是：

--font-app:
  "Noto Serif SC",
  "Inter",
  "PingFang SC",
  "Microsoft YaHei",
  system-ui,
  sans-serif;

--font-code:
  "JetBrains Mono",
  ui-monospace,
  "Cascadia Code",
  "Source Code Pro",
  monospace;

这套方案解决了网络依赖，但完整的 Noto Serif SC 文件约 10.7 MB，成为站点最重的静态资源。

2026-05-29 — 在体积和一致性之间反复取舍

为了降低传输体积，一度移除本地中文字体，让不同平台分别回退到 PingFang SC、Microsoft YaHei 和 system-ui。这种方式最轻，但不同系统上的中文观感差异较大，也失去了想要的宋体阅读风格。

之后尝试通过 Fontsource 引入 Noto Sans 和 Noto Serif SC，只保留现代浏览器需要的 WOFF2。中文字体体积降到约 3.06 MB，但直接引用 node_modules 内部字体路径不够稳，构建产物也不容易验证。

2026-05-30 — 暂时回到系统字体

为了先保证构建链路简单可靠，中文正文暂时改回系统衬线字体栈：

--font-app:
  "Songti SC",
  "STSong",
  "Source Han Serif SC",
  "Noto Serif CJK SC",
  "SimSun",
  serif;

代码字体继续使用本地 JetBrains Mono。这个阶段不再追求各平台字形完全一致，优先保证零外部请求和较小的资源体积。

2026-06-22 — Noto 全家族与中文分包

最终方案统一使用 Noto 字体家族：

• 英文正文使用 Noto Serif
• 简体中文使用 Noto Serif SC
• 行内代码、代码块和等宽数字使用 Noto Sans Mono

三套字体全部托管在站点自身的 public/fonts/ 目录，不请求 Google Fonts 或其他境外字体 CDN。

中文字体采用 unicode-range 分包，将 Noto Serif SC 拆成 101 个 WOFF2 文件。浏览器会根据当前页面出现的字符，只下载对应分片，而不是一次加载完整字库。

字体资源整体情况如下：

Noto Serif       2 个拉丁字符分片    约 0.21 MB
Noto Serif SC    101 个中文分片      完整约 5.75 MB
Noto Sans Mono   2 个拉丁字符分片    约 0.18 MB

这里的 5.75 MB 是服务器保存的完整中文字库总量，不是单个页面的下载量。已加载的分片可以被浏览器长期缓存，访问其他文章时只补充尚未缓存的字符分片。

最终字体变量为：

--font-app:
  "Noto Serif Variable",
  "Noto Serif SC Variable",
  "Songti SC",
  "STSong",
  "Source Han Serif SC",
  "Noto Serif CJK SC",
  "SimSun",
  serif;

--font-code:
  "Noto Sans Mono Variable",
  ui-monospace,
  "Cascadia Mono",
  "Cascadia Code",
  monospace;

原来的 JetBrains Mono 文件和声明已经移除。Tailwind 的 font-mono 也指向 --font-code，归档日期等界面元素会和代码区域使用同一套等宽字体。

字体 CSS 最初通过全局样式中的 @import 加载，但经过 Tailwind 和 PostCSS 展开后触发了 @import must precede all other statements 警告。最终改为在 Layout.astro 的 <head> 中加载三份同源字体样式表，并通过 getAssetPath() 生成路径，以兼容子目录部署。