博客模板个人化改造详解

这次提交的核心目标，是把上游 astro-erudite 博客模板改造成 晖绝的个人主页。它不是一次彻底重写，而是在尽量保留模板原有博客、作者、标签、RSS、Sitemap、暗色模式、MDX、项目集合等能力的前提下，完成站点身份、中文化、个人介绍、项目详情、经历页、品牌资源和 SEO 的第一轮个人化。

如果你也想拿这个博客模板改成自己的个人主页，可以把本文当成逐文件改造清单。

一、改造总览

1. 这次提交做了什么

提交影响范围很大，主要包括：

• 全站身份从 astro-erudite 换成 晖绝的个人主页。
• 站点域名从模板站点 https://astro-erudite.vercel.app 换成 https://huijue.top。
• 作者从模板作者 enscribe / jktrn 换成个人作者 晖绝 / aisspire。
• 顶部导航从模板的博客和作者入口，改成个人站更常见的 项目 / 经历 / 博客 / 关于。
• 社交链接从模板作者 GitHub、Twitter、邮箱，改成个人 GitHub、邮箱、RSS。
• 首页从模板介绍页，改成个人主页入口。
• 关于页从模板介绍，改成个人资料页。
• 新增经历页 /experience。
• 新增项目列表页 /projects 和项目详情页 /projects/[id]。
• 项目数据模型支持站内详情，不再强制要求外链。
• 模板文章统一换作者并设为草稿，保留为 MDX 写法参考，但不展示。
• 文章、标签、作者、分页、目录、上一页下一页等 UI 文案中文化。
• favicon、Logo、Web App 图标、社交分享图替换为个人品牌资源。
• SEO 的 canonical、Open Graph 图片、robots sitemap 地址改成个人域名。
• 包管理从 Bun 锁文件切到 npm 锁文件。
• 新增根目录 使用说明.md，用于说明个人博客第一阶段怎么改。

2. 改造后的站点结构

这次改造后，站点主要页面变成：

3. 最推荐的个人化顺序

拿到模板后，建议按这个顺序改：

1. 改 src/consts.ts：站点名、描述、作者、域名、导航、社交链接。
2. 改 astro.config.ts：正式站点域名。
3. 改 src/content/authors/*.md：作者名、头像、简介、链接。
4. 改 src/pages/index.astro：首页改成个人入口。
5. 改 src/pages/about.astro：关于页改成个人介绍。
6. 新增或调整 src/pages/experience.astro：经历页。
7. 改 src/content.config.ts 和 src/content/projects/*.md：项目字段和项目内容。
8. 新增 src/pages/projects/index.astro 与 src/pages/projects/[...id].astro：站内项目列表和详情。
9. 改 src/components/project-card.astro：项目卡片指向站内详情。
10. 把模板文章的 authors 改成自己的作者 ID，把暂时不用的文章设为 draft: true。
11. 全站中文化：页面标题、按钮、分页、阅读时间、目录、404 等。
12. 替换 public 里的 Logo、favicon、manifest 图标、社交分享图。
13. 检查 SEO 组件、robots、RSS、sitemap 是否都使用自己的域名。
14. 运行 npm run build，及时发现内容字段、图片路径、动态路由和类型错误。

二、全站基础配置

1. src/consts.ts

这是个人化改造的第一入口。提交里把模板默认配置改成：

• SITE.title：从 astro-erudite 改为 晖绝的个人主页。
• SITE.description：从模板描述改为 记录项目经历，学习笔记与成长历程。
• SITE.href：从 https://astro-erudite.vercel.app 改为 https://huijue.top。
• SITE.author：从 jktrn 改为 晖绝、huijue。
• SITE.locale：从 en-US 改为 zh-CN。
• NAV_LINKS：从 blog / authors / about 改为 项目 / 经历 / 博客 / 关于。
• SOCIAL_LINKS：从模板 GitHub、Twitter、邮箱、RSS，改为个人 GitHub、邮箱、RSS。

个人化时必须改这里，因为它影响：

• 顶部站点标题。
• 页面 SEO 默认标题和描述。
• RSS 标题。
• 导航菜单。
• 页脚社交图标。
• Open Graph 的站点名和语言。

建议替换为自己的信息：

1
export const SITE = {
2
  title: '你的名字或昵称',
3
  description: '一句话说明这个站点是什么',
4
  href: 'https://你的域名',
5
  author: '你的名字',
6
  locale: 'zh-CN',
7
  featuredPostCount: 2,
8
  postsPerPage: 3,
9
}

NAV_LINKS 不要放太多。个人站第一阶段推荐保留：

• /projects：项目。
• /experience：经历。
• /blog：博客。
• /about：关于。

如果你不需要经历页，可以删掉 /experience；如果你只想做博客，可以只保留 /blog 和 /about。

2. astro.config.ts

提交里改了两个点：

• site 从模板域名改成 https://huijue.top。
• tailwindcss() 被写成 tailwindcss() as any。

site 很重要。Astro 会用它生成 sitemap、canonical、RSS、资源绝对地址等。如果这里不改，部署后可能出现：

• 分享链接还是模板域名。
• sitemap 指向模板域名。
• RSS 或 Open Graph 图片地址错误。
• robots 里 sitemap 地址不对。

个人化时务必改成正式域名：

1
export default defineConfig({
2
  site: 'https://example.com',
3
})

tailwindcss() as any 是为了绕过当前依赖版本下 Vite 插件类型不匹配的问题。如果你升级或降级 Astro、Vite、Tailwind 后类型正常，可以再评估是否去掉。

3. package.json

提交里做了这些变化：

• 包名从 astro-erudite 改为 huijue-homepage。
• 多个 Astro 相关依赖从固定版本改为带 ^ 的较新版本。
• astro 从 6.0.2 改为 ^6.3.1。
• @tailwindcss/vite 从 ^4.0.7 改为 ^4.3.0。
• 新增显式依赖 vite: 7.3.3。
• 保留原来的脚本：
  • npm run dev
  • npm run build
  • npm run preview
  • npm run prettier

个人化时建议至少改：

1
{
2
  "name": "your-homepage"
3
}

不要随手升级依赖。模板改造阶段优先让内容和页面稳定，依赖升级会把问题变复杂。确实需要升级时，改完必须跑：

npm run build

4. bun.lock 与 package-lock.json

提交删除了 bun.lock，新增了 package-lock.json。这表示项目从 Bun 锁文件切换到 npm 锁文件。

个人化时要选定一种包管理器：

• 如果用 npm：保留 package-lock.json，使用 npm install、npm run dev、npm run build。
• 如果用 Bun：保留 bun.lock 或重新生成 Bun 锁文件，使用 bun install、bun run dev。

不要同时维护多个锁文件，否则团队协作或部署平台可能安装出不同依赖树。

5. .gitignore

提交里给 .gitignore 增加过：

• /.agents
• /docs

当前工作区实际 .gitignore 保留了 /.agents，没有保留 /docs。如果以后要把 docs 目录里的文档纳入版本控制，就不要忽略 /docs。

个人化时可以忽略：

• 本地智能体配置：/.agents
• 构建输出：dist/
• Astro 缓存：.astro/
• 依赖目录：node_modules/
• 本地环境变量：.env

但像本文这种项目说明文档，如果希望长期留在仓库里，就应该让 docs 可提交。

三、品牌资源与图标

1. public/static/logo.svg

模板原来的 logo.svg 是灰色条纹样式。提交里替换成新的个人 Logo SVG。

这个文件通常用于站点品牌展示或资源引用。个人化时可以替换为：

• 自己的姓名首字母 Logo。
• 个人头像的矢量版。
• 简洁的图形标识。

注意事项：

• 如果 SVG 是黑色单色图标，暗色模式下可能看不清。
• 如果要在 Astro 的 Image 组件中导入，文件要能被 Astro 静态处理。
• Logo 最好保持简单，顶部导航中实际显示尺寸很小。

2. public/static/mylogo.svg

这是提交新增的个人 Logo SVG，内容与新的 logo.svg 基本一致。

src/components/header.astro 改成导入这个文件：

1
import logo from '../../public/static/mylogo.svg'

个人化时你有两种做法：

• 只维护 public/static/logo.svg，然后让 Header 继续用 logo.svg。
• 维护一个单独的 mylogo.svg，然后在 Header 中导入它。

如果不需要两份 Logo，建议保留一份，避免以后替换时漏改。

3. public/static/logo.png

提交替换了 PNG Logo，文件大小从约 2 KB 变成约 19 KB。这个文件在本次改造中有两个用途：

• 作者头像：src/content/authors/huijue.md 使用 /static/logo.png。
• 关于页头像：src/pages/about.astro 使用 /static/logo.png。

个人化时，如果你想用真实头像或头像风格图片，改这里最直接。

4. public/favicon.svg

提交把原来的内嵌 PNG favicon SVG，替换成当前个人 Logo 的矢量路径，并加入暗色模式样式：

1
@media (prefers-color-scheme: dark) { svg { color: #ffffff; } }

这意味着浏览器在暗色主题下会把图标变成白色，避免黑色图标看不清。

个人化时需要注意：

• favicon SVG 尽量使用 currentColor，方便适配暗色模式。
• 不要把过大的 base64 图片塞进 SVG，维护困难。
• 同时检查 PNG 和 ICO 版本是否一致。

5. public/favicon-96x96.png、public/favicon.ico、public/apple-touch-icon.png

这些二进制资源在提交中被替换，作用分别是：

• 浏览器标签页 PNG 图标。
• 旧浏览器或系统使用的 .ico 图标。
• iOS 添加到主屏幕时使用的 Apple Touch Icon。

个人化时如果只替换 SVG，不替换这些文件，部分设备上仍会显示模板图标。

6. public/web-app-manifest-192x192.png 与 public/web-app-manifest-512x512.png

这两个文件是 PWA/Web App manifest 使用的图标。提交里也替换成个人图标。

如果用户把你的网站添加到手机主屏幕，这两个图标会被使用。

7. public/static/1200x630.png

这是社交分享图，常用于 Open Graph 和 Twitter Card。提交里替换了这个图。

个人化时建议做成 1200x630 的横图，内容可以是：

• 站点名。
• 你的名字。
• 一句话定位。
• 简洁 Logo。

它会影响微信、Twitter/X、Discord、Slack、Telegram 等平台预览效果。

8. public/site.webmanifest

提交里把：

• name 从 astro-erudite 改成 晖绝的个人主页。
• short_name 从 astro-erudite 改成 晖绝。

个人化时必须改这里，否则网站添加到桌面或手机主屏幕后，显示的仍是模板名。

这个文件是 JSON，不能写注释。

四、SEO 与 Head 组件

1. src/components/favicons.astro

提交里新增：

1
import { SITE } from '@/consts'

然后把：

1
<meta name="apple-mobile-web-app-title" content="astro-erudite" />

改成：

1
<meta name="apple-mobile-web-app-title" content={SITE.title} />

个人化意义：以后只要改 src/consts.ts 的 SITE.title，Apple Web App 标题就会跟着变，不需要在多个文件重复改模板名。

2. src/components/head.astro

提交删除了这一行：

1
<link rel="manifest" href="/site.webmanifest" />

因为 Favicons 组件中已经有：

1
<link rel="manifest" href="/site.webmanifest" />

这样可以避免 manifest 重复声明。

个人化时要注意：通用 head 里不要重复写 favicon、manifest、RSS 等链接，最好集中在专门组件里。

3. src/components/page-head.astro

提交里做了几个关键 SEO 修正：

• 新增 canonical = new URL(Astro.url.pathname, SITE.href)。
• Open Graph 图片改为 new URL('/static/1200x630.png', SITE.href)。
• canonical 链接从固定 SITE.href 改为当前路径对应的绝对地址。
• og:url 从 Astro.url 改为 canonical。

改造前的问题是：所有页面 canonical 都可能指向首页，不利于 SEO。

个人化时这里要确认：

• SITE.href 是正式域名。
• canonical 应该包含当前路径。
• og:image 应该是完整绝对 URL。
• og:locale 使用中文站点的 zh-CN。

4. src/components/post-head.astro

文章页 SEO 也做了类似修正：

• canonical 改为当前文章路径。
• 默认分享图改为基于 SITE.href。
• 如果文章有封面图，则用 new URL(post.data.image.src, SITE.href) 生成绝对地址。
• og:url 改为 canonical。

个人化时要检查文章封面图路径。文章 frontmatter 里的 image 通常是：

1
image: './banner.png'

Astro 会处理成资源路径，post.data.image.src 再拼成完整 URL。

5. src/pages/robots.txt.ts

提交里把 sitemap URL 的生成方式改为：

1
const sitemapURL = new URL('sitemap-index.xml', site ?? 'https://huijue.top')

个人化意义：当 Astro 没有传入 site 时，也能回退到个人域名。

如果你改成自己的站点，记得把回退地址也改掉：

1
const sitemapURL = new URL('sitemap-index.xml', site ?? 'https://example.com')

更稳的做法是从 SITE.href 读取，避免域名散落在多个文件。

五、导航与页脚

1. src/components/header.astro

提交里做了两处改动：

• Logo 导入从 public/static/logo.svg 改为 public/static/mylogo.svg。
• Logo 图片增加 dark:invert，暗色模式下反色。

这让顶部导航显示个人 Logo，并避免黑色 Logo 在暗色模式中不可见。

个人化时需要改：

• Logo 文件路径。
• Logo 的 alt 文案。
• 是否需要 dark:invert。
• 站点标题来自 SITE.title，不必在 Header 里硬编码。

导航文字来自 NAV_LINKS，所以主导航优先改 src/consts.ts。

2. src/components/footer.astro

提交把页脚从：

Made with love by enscribe.

改成：

Built by 晖绝, based on astro-erudite.

并把作者链接从 https://github.com/jktrn 改为 https://github.com/aisspire，同时保留上游模板链接。

个人化时建议页脚包含：

• 当前年份版权。
• 你的名字或昵称。
• 可选：模板来源链接。
• 社交图标，来自 SOCIAL_LINKS。

保留模板来源是好习惯，也方便以后回看上游。

六、首页、关于页、经历页

1. src/pages/index.astro

首页是本次改造最重要的页面之一。提交把模板的英文介绍页改成中文个人主页入口。

改造前首页介绍的是：

• erudite 这个词。
• 模板基于 Astro、Tailwind、shadcn/ui。
• 模板 GitHub 链接。
• 模板理念文章。
• Latest posts。

改造后首页改成：

• 个人主页 / 项目经历 / 学习笔记。
• 你好，我是晖绝。
• 英文 ID ais_spire。
• 站点定位：求职、成长记录、项目经历、学习笔记。
• GitHub 和邮箱联系方式。
• 四个入口按钮：
  • 查看项目：/projects
  • 了解经历：/experience
  • 阅读博客：/blog
  • 联系我：mailto:ais@huijue.top
• Latest posts 改成 最新文章。
• See all posts 改成 查看全部文章。

还保留了一段被注释掉的三栏卡片结构，作为以后扩展经历、项目、博客简介的参考。

个人化时首页建议只回答四个问题：

• 我是谁。
• 我做什么方向。
• 访客应该先看哪里。
• 怎么联系我。

不要第一阶段就把所有经历、所有项目、所有技能堆到首页。更清晰的结构是：首页做入口，详细内容分流到项目页、经历页、关于页和博客页。

2. src/pages/about.astro

提交把关于页从模板说明改成个人资料页。

改造前关于页：

• 介绍 astro-erudite 是什么。
• 链接到模板理念文章。
• 展示示例项目列表。

改造后关于页：

• 标题从 About 改为 关于。
• 面包屑从 About 改为 关于。
• 增加头像 /static/logo.png。
• 增加 关于我 标题。
• 写入个人身份：晖绝、英文 ID、南京邮电大学本科生。
• 写入站点用途：教育经历、项目实践、学习笔记、求职信息。
• 增加基本信息列表：
  • 当前身份。
  • 学校。
  • 毕业年份。
  • 主要方向。
  • 站点定位。
• 增加联系方式：GitHub、邮箱。
• 把原来的项目卡片区注释掉，说明项目已移动到 /projects。

个人化时关于页适合写得比首页更完整：

• 教育背景。
• 技术方向。
• 当前目标。
• 项目经历摘要。
• 联系方式。
• 可选的简历下载入口。

如果你新增了独立项目页，就不必在关于页重复完整项目列表。

3. src/pages/experience.astro

这是提交新增页面，对应路由 /experience。

页面内容包括：

• 页面标题：经历。
• SEO 描述：晖绝的教育经历、技术方向与阶段记录。
• 面包屑图标：lucide:briefcase-business。
• 教育背景。
• 技术方向。
• 项目实践说明，并链接到 /projects。
• 待补充内容：
  • 课程与学习阶段。
  • 竞赛或活动经历。
  • 实习或团队协作经历。
  • 阶段性总结与求职准备。

个人化时，如果你是求职向个人站，经历页很值得保留。建议后续改成时间线结构：

• 教育经历。
• 实习经历。
• 竞赛经历。
• 课程项目。
• 开源或个人项目阶段。
• 求职准备阶段。

如果你只是写博客，不需要经历页，可以从 NAV_LINKS 中删掉 /experience，并删除或保留该页面。

七、项目系统改造

1. src/content.config.ts

提交修改了项目集合 schema：

• 新增 note?: string。
• link 从必填 z.url() 改成可选 z.url().optional()。

改造前，项目必须有外链：

1
link: z.url()

改造后，项目可以没有外链：

1
note: z.string().optional()
2
link: z.url().optional()

这个改动很关键。个人求职站里很多项目可能是：

• 课程项目。
• 私有项目。
• 比赛项目。
• 团队项目。
• 已归档项目。
• 代码不便公开的项目。

如果强制要求 link，这些项目就不好写。改成可选后，可以把重点放在项目背景、职责、技术方案和复盘上。

note 字段用于显示项目状态，例如：

• 开源项目
• 待补充
• 私有/归档
• 课程项目
• 比赛项目

个人化时，如果你还想增加更多字段，可以在这里扩展，例如：

• role：你的职责。
• repo：源码仓库。
• demo：在线演示。
• highlights：项目亮点。
• status：项目状态。

但不要一开始扩太多字段。Markdown 正文已经足够承载复杂说明。

2. src/components/project-card.astro

提交把项目卡片从外链卡片改成站内详情入口。

改造前：

1
href={project.data.link}
2
external

改造后：

1
href={`/projects/${project.id}`}

并增加：

• 项目 note 徽标。
• Present 改成 至今。

这意味着 /projects 列表中的每张卡片都会进入站内详情页，而不是直接跳 GitHub 或外部链接。

个人化时，如果你希望项目卡片直接跳外部链接，可以恢复 href={project.data.link}。但求职向个人站更推荐站内详情，因为你可以完整写：

• 项目背景。
• 你的职责。
• 技术栈。
• 难点。
• 结果。
• 复盘。

3. src/pages/projects/index.astro

这是提交新增的项目列表页。

页面逻辑：

• 调用 getAllProjects() 获取所有项目。
• 页面标题为 项目。
• SEO 描述为 晖绝的项目经历与实践记录。
• 显示一段说明文字。
• 遍历项目并渲染 ProjectCard。

个人化时要改：

• 页面描述。
• 开头说明文案。
• 是否按项目类型分组。
• 是否只展示精选项目。

4. src/pages/projects/[...id].astro

这是提交新增的项目详情页。

页面逻辑：

• getStaticPaths() 从 getAllProjects() 生成所有项目详情路由。
• 使用 render(project) 渲染 Markdown 正文。
• 顶部显示面包屑：项目 / 当前项目名。
• 如果项目有图片，显示大图。
• 显示项目名、note、描述、日期、标签。
• 正文使用 <Content /> 渲染。

这个页面让项目内容从“卡片摘要”升级为“完整项目说明”。

个人化时要注意：

• 每个 src/content/projects/*.md 文件名就是项目路由 ID。
• 例如 project-a.md 会生成 /projects/project-a。
• 如果改文件名，URL 也会变。
• 项目详情页目前没有单独显示 link 外链。如果你希望展示 GitHub 或 Demo，需要在详情页里加入按钮，或者在项目 Markdown 正文中手写链接。

5. src/content/projects/project-a.md

提交把模板 Project A 改成真实项目样例 Codex Session Manager。

frontmatter 包含：

• name
• description
• note: '开源项目'
• tags
• image
• link

正文包含：

• 项目背景。
• 核心功能。
• 技术栈。
• 项目状态。

这是一个“开源项目”的写法模板。个人化时可以按这个结构写真实项目。

6. src/content/projects/project-b.md

提交把模板项目改成 Java 后端项目模板。

它是占位项目，适合未来替换为真实 Java/Spring Boot 项目。

正文结构包括：

• 项目背景。
• 我的职责。
• 技术栈。
• 核心功能。
• 难点与解决。
• 项目状态。

这类结构很适合面试展示。不要只写技术栈，要写清楚你承担了什么、解决了什么问题。

7. src/content/projects/project-c.md

提交把模板项目改成 课程 / 私有项目模板。

它强调即使代码不公开，也能写清楚：

• 项目背景。
• 我的职责。
• 技术方案。
• 项目成果。
• 复盘。
• 项目状态。

个人站不要求所有项目都有 GitHub。没有公开代码时，项目详情页反而更重要，因为它能说明你的真实贡献。

八、作者系统改造

1. 删除 src/content/authors/enscribe.md

提交删除了模板作者：

• name: enscribe
• avatar: gravatar
• website: enscribe.dev
• twitter: enscry
• github: jktrn
• mail: jason@enscribe.dev

个人化时，模板作者信息必须换掉，否则文章卡片和文章详情仍会显示模板作者。

2. 新增 src/content/authors/huijue.md

提交新增个人作者：

1
---
2
name: '晖绝'
3
avatar: '/static/logo.png'
4
bio: '记录项目经历，学习笔记与成长历程'
5
website: 'https://huijue.top'
6
github: 'https://github.com/aisspire'
7
mail: 'ais@huijue.top'
8
---

文件名 huijue.md 很重要。博客文章 frontmatter 中的：

1
authors: ['huijue']

会通过这个 ID 找到作者资料。

个人化时建议：

• 文件名用稳定英文 ID，例如 yourname.md。
• 文章里的 authors 用同一个 ID。
• avatar 可以用 /static/avatar.png 或外部 URL。
• 邮箱、GitHub、网站都换成自己的。

3. src/pages/authors/index.astro

提交把作者列表页中文化：

• 页面标题 Authors 改为 作者。
• 面包屑 Authors 改为 作者。
• 空状态 No authors found. 改为 暂无作者。

个人站可以不把 /authors 放入主导航，但作者页保留没有坏处。文章详情里的作者链接仍然可以跳到作者资料页。

4. src/pages/authors/[...id].astro

提交把作者详情页中文化：

• 标题从 ${name} (Author) 改为 ${name}（作者）。
• 描述从 Profile of ${name}. 改为 ${name} 的作者资料。。
• 面包屑从 Authors 改为 作者。
• Posts by xxx 改为 xxx 的文章。
• 空状态改为 这位作者暂无文章。

个人化时，如果你只做单作者博客，这个页面可以保留。以后如果加入访客作者或转载作者，也能扩展。

九、博客内容改造

1. 模板文章统一换作者

提交把多个模板文章的作者从 enscribe 改成 huijue，例如：

• src/content/blog/2023-post/index.mdx
• src/content/blog/2024-post/index.mdx
• src/content/blog/callouts-component/index.mdx
• src/content/blog/mobile-nav-and-subposts/index.mdx
• src/content/blog/mobile-nav-and-subposts/mobile-navigation.mdx
• src/content/blog/mobile-nav-and-subposts/subposts.mdx
• src/content/blog/rehype-patch/index.mdx
• src/content/blog/the-state-of-static-blogs/index.mdx

个人化时要把所有文章 frontmatter 的 authors 改成自己的作者 ID。

2. 模板文章设为草稿

提交给模板文章增加了：

1
draft: true

这样它们仍然保留在仓库中，可作为 MDX、Callout、子文章、目录、代码块等写法参考，但不会显示在博客列表、首页最新文章、标签页等公开入口。

个人化时推荐这样处理模板文章：

• 暂时不用，但想保留参考：设为 draft: true。
• 完全不需要：删除对应文章目录。
• 想作为自己的文章：改标题、描述、日期、标签、正文、作者，去掉 draft: true。

3. src/pages/blog/[...page].astro

提交把博客列表页中文化：

• 页面标题 Blog 改为 博客。
• 面包屑 Blog 改为 博客。
• 分页面包屑 Page 1 改为 第 1 页。

4. src/pages/blog/[...id].astro

提交把文章详情页中文化：

• 面包屑 Blog 改为 博客。
• 总阅读时间从 (... total) 改为 (共 ...)。
• 子文章数量从 1 subpost / n subposts 改为 n 篇子文章。
• 回到顶部按钮从 Scroll to top 改为 回到顶部。
• 修复文件末尾缺少换行。

个人化时，这个页面还可以继续改：

• 是否展示作者。
• 是否展示标签。
• 是否展示阅读时间。
• 是否展示目录。
• 是否保留子文章功能。

模板的子文章功能比较有价值，建议先保留，不要急着删。

5. src/components/blog-card.astro

提交把博客卡片里的子文章数量文案从英文改为中文：

1
{subpostCount} 篇子文章

个人化时，博客卡片主要影响首页最新文章和博客列表页。

十、标签、分页、目录、阅读时间中文化

1. src/pages/tags/index.astro

提交把标签列表页中文化：

• Tags 改为 标签。

2. src/pages/tags/[...id].astro

提交把标签详情页中文化：

• 标题从 Posts tagged with "tag" 改为 标签：tag。
• 描述从 A collection of posts tagged with tag. 改为 包含 tag 标签的文章。
• 面包屑 Tags 改为 标签。

3. src/components/ui/pagination.tsx

提交把分页组件中文化：

• aria-label="pagination" 改为 aria-label="分页"。
• Go to previous page 改为 上一页。
• Previous 改为 上一页。
• Go to next page 改为 下一页。
• Next 改为 下一页。
• More pages 改为 更多页面。

这个组件是 React 组件，影响博客分页。

4. src/lib/utils.ts

提交改了日期和阅读时间：

• 日期格式从 en-US 改为 zh-CN。
• 阅读时间从 1 min read 改为 1 分钟阅读。

个人化时如果站点是中文，这两个必须改，否则页面会中英混杂。

如果你想更适合中文阅读，可以进一步调整字数统计逻辑。当前 calculateWordCountFromHtml 用空白拆分单词，对中文文章的阅读时间估算可能不准。

5. src/lib/data-utils.ts

提交把目录章节默认标题从：

1
title: 'Overview'

改为：

1
title: '概览'

这个值用于文章目录和子文章目录。

6. src/components/toc-header.astro

提交把移动端目录初始文案从 Overview 改为 概览。

同时脚本里的：

1
const INITIAL_OVERVIEW_TEXT = '概览'

也同步改了。

个人化时，如果你保留移动端目录，这里的语言要和站点一致。

7. src/components/subposts-header.astro

提交把移动端子文章导航里的总阅读时间文案：

(x total)

改为：

(共 x)

8. src/components/subposts-sidebar.astro

桌面端子文章侧边栏做了同样的中文化，把 (x total) 改成 (共 x)。

9. src/components/post-navigation.astro

提交把文章上一篇/下一篇导航中文化：

• Previous Post 改为 上一篇。
• Next Post 改为 下一篇。
• Previous Subpost 改为 上一篇子文章。
• Next Subpost 改为 下一篇子文章。
• Parent Post 改为 返回主文章。
• No older subpost 改为 没有更早的子文章。
• No newer subpost 改为 没有更新的子文章。
• You're at the oldest post! 改为 已经是最早的文章。
• You're at the newest post! 改为 已经是最新的文章。
• No parent post 改为 没有主文章。

个人化时，所有用户能看到的英文都应该扫一遍。可以用：

rg "Previous|Next|Overview|Blog|Authors|Tags|Scroll to top|Present|min read|No posts"

十一、404 页面和主题切换

1. src/pages/404.astro

提交把 404 页面中文化：

• 404: Page not found 改为 404：页面不存在。
• Oops! The page you're looking for doesn't exist. 改为 你访问的页面不存在，可能已经移动或尚未创建。
• Go to home page 改为 返回首页。

个人化时 404 页面可以保持简洁，至少要有返回首页入口。

2. src/components/theme-toggle.astro

提交把主题按钮中文化：

• title="Toggle theme" 改为 title="切换主题"。
• 屏幕阅读器文本 Toggle theme 改为 切换主题。

这类 title 和 sr-only 文案平时不显眼，但会影响可访问性和整体完成度。

十二、根目录使用说明

提交新增了根目录 使用说明.md。它是一份轻量改造指南，说明：

• 最推荐先修改哪些文件。
• 页面和文件对应关系。
• src/consts.ts 怎么改。
• 首页怎么改。
• 关于页怎么改。
• 博客文章怎么写。
• 项目内容怎么写。
• 哪些内容适合第二阶段再改。
• 哪些文件不推荐随意改。
• 推荐的轻量改造顺序。
• 模板默认值备忘。

现在本文档放在 docs 目录下，定位更细：它不是泛化经验，而是专门解释 8f18d806 这次提交中每一类改动为什么做、个人化时对应应该改哪里。

如果后续整理文档结构，建议把根目录 使用说明.md 也移动到 docs，例如：

docs/使用说明.md
docs/8f18d806-博客模板个人化改造详解.md
docs/template-personalization-guide.md

这样仓库根目录会更干净。

十三、逐文件变更清单

1. 配置和依赖

2. 品牌资源

3. 组件

4. 内容配置和工具函数

5. 内容文件

6. 页面

十四、个人化必改清单

如果你只想快速把模板改成自己的站点，最少要改这些：

十五、可以第二阶段再改的内容

这些不是第一阶段必须项：

• 重做全局视觉风格。
• 新增简历下载。
• 项目详情页增加 GitHub/Demo 按钮。
• 经历页改成时间线组件。
• 中文阅读时间按中文字数重新估算。
• 首页增加精选项目区。
• 博客文章重新设计封面。
• 增加搜索。
• 增加评论。
• 增加访问统计。

第一阶段最重要的是：模板不再像模板，站点信息、作者、首页、关于、项目和域名都属于你。

十六、改造后的验证建议

每次改完这些文件，都建议运行：

npm run build

尤其是改了以下内容时：

• src/content.config.ts
• src/content/projects/*.md
• src/content/blog/**/*.mdx
• src/pages/projects/[...id].astro
• astro.config.ts
• src/components/page-head.astro
• src/components/post-head.astro

常见错误包括：

• Markdown frontmatter 字段不符合 schema。
• 项目图片路径不对。
• 作者 ID 不存在。
• 动态路由生成失败。
• SITE.href 或 Astro.site 为空导致 URL 生成错误。
• 依赖升级后 TypeScript 类型不匹配。

还可以用这些搜索命令扫漏：

rg "astro-erudite|enscribe|jktrn|astro-erudite.vercel.app"
rg "Authors|Tags|Blog|Previous|Next|Overview|Present|Toggle theme|Scroll to top"
rg "huijue.top|aisspire|ais@huijue.top"

前两条用于发现没改干净的模板残留和英文文案。第三条用于发现个人信息散落在哪里，方便以后换域名或换邮箱。

十七、这次提交的改造原则

这次提交体现了几个值得复用的原则：

1. 先改身份，再改视觉。站点名、作者、域名、导航比颜色和布局更重要。
2. 保留模板能力，不急着删除。作者页、标签页、子文章、RSS、Sitemap 都保留了。
3. 私有项目也要能展示。项目 link 改可选，详情页用 Markdown 承载说明。
4. 首页做入口，不做信息仓库。详细内容分到项目、经历、关于、博客。
5. 中文化要扫组件细节。按钮、aria-label、目录、分页、阅读时间都要统一。
6. SEO 不能只改标题。canonical、og:url、og:image、robots、manifest 都要改。
7. 模板文章先设草稿。保留参考价值，同时不让模板内容出现在公开站点。

按这个思路改，模板会逐步变成自己的长期个人站基础，而不是一次性魔改后难以维护的页面。