LT-IENG 个人网站更新指南

一、项目概览

属性	值
名称	LT-IENG 个人网站
域名	lt-ieng.cn
框架	Astro 5.x（静态站点生成器）
样式	Tailwind CSS v4 + @tailwindcss/typography
托管	GitHub Pages（零服务器成本）
部署	GitHub Actions 自动构建部署
国内合规	支持 ICP 备案（纯静态，GitHub Pages 直出）

二、从 Hexo 到 Astro：演进历程

旧架构（2026.6 之前）

Hexo 8.x + Butterfly 5.x 主题
├── 优点：开箱即用，社区成熟
├── 缺点：
│   ├── 主题模板固定，自定义能力弱
│   ├── EJS/Pug 模板语言，做复杂动效非常困难
│   ├── 首页只能按配置排列，无法自由设计
│   ├── 视觉风格和大量 Hexo 博客雷同
│   └── Nunjucks 模板引擎与 LaTeX 公式冲突
└── 构建：hexo generate → public/ → deploy to gh-pages

为什么迁移

痛点	旧方案无法解决的原因
首页太普通	Butterfly 主题是固定布局，改不了 Hero 区、加不了粒子背景
板块不突出	分类页只是标题链接列表，没有视觉层次
动效做不了	EJS 模板里无法用 Canvas、GSAP、IntersectionObserver
设计同质化	暖白色调 + 通用排版 = 和千万个 Hexo 博客长得一样
Nunjucks 冲突	`{{ }}` `{% %}` 和 LaTeX 花括号冲突，需要包裹

新架构（2026.6 至今）

Astro 5.x + Tailwind CSS v4
├── 核心优势：
│   ├── 纯静态输出 → GitHub Pages 完美适配，零服务器
│   ├── .astro 组件化 → 首页自由设计，不受任何主题限制
│   ├── Content Collections → Markdown 写博客，类型安全
│   ├── 默认 0 JS → 只在需要处加载（粒子、搜索、滚动动效）
│   └── Tailwind CSS v4 + @theme → 设计令牌一套改全站
└── 构建：npm run build → dist/ → GitHub Actions 自动部署

新架构相比旧架构的改进

维度	Hexo + Butterfly	Astro（当前）	提升
首页设计	固定模板，不可定制	Canvas 粒子 + 精选轮播 + 板块堆叠	从模板到自定义
板块展示	文字链接列表	四个全屏卡片，2×2 文章网格，堆叠切换	从列表到沉浸式
动效	无	Canvas 粒子互动、卡片堆叠滚动、目录高亮、搜索弹窗	从静态到交互
写作体验	`hexo new`	`npm run new` 交互式 + 板块文件夹	等价，都简单
Markdown	Nunjucks 冲突需	remark 插件自动处理，零冲突	从手动规避到自动
构建速度	一般	14 页 2 秒	快
CSS 定制	覆盖主题 CSS	自己的 CSS 变量系统，一处改全局	从 hack 到设计系统
搜索	无（需第三方插件）	弹窗实时搜索，Ctrl+K	从无到有
目录导航	静态目录	Sticky 侧栏 + IntersectionObserver 高亮	从装饰到可用
文章渲染	自定义模板	Tailwind Typography，VSCode 同款排版	从自定义到标准

迁移时保留了什么

所有 6 篇原始文章的内容一字未改
域名 lt-ieng.cn，GitHub Pages 托管方式不变
写作体验：依然是 Markdown → 构建 → 推送上线的流程
KaTeX 数学公式支持
CC BY-NC-SA 4.0 许可协议

新增了什么

Canvas 粒子动态背景（鼠标互动）
首页精选文章横向自动轮播（hover 暂停，6 篇 featured 文章）
四大板块全屏卡片堆叠滚动效果
板块内 2×2 文章网格（pinned 手动精选 + 自动补位）
全站搜索弹窗（Ctrl+K 快捷键，实时筛选）
Sticky 目录侧栏 + 滚动高亮 + 移动端悬浮按钮
文章封面图全宽横幅（hero 字段）
时间轴按年归档页面
板块独立页面（/section/板块名）
文章卡片响应式设计
暖色系品牌设计系统（可一键换色）

三、架构总览

核心架构原则

网站是完全静态的：Markdown 文章 → Astro 构建 → 纯 HTML/CSS/JS → GitHub Pages

没有后端服务器，没有数据库，不依赖任何第三方 CMS。

目录结构

LTwebsite/
├── src/
│   ├── pages/                    # 路由页面
│   │   ├── index.astro           # 首页（Hero + 简历 + 四板块堆叠）
│   │   ├── about.astro           # 关于页
│   │   ├── archives.astro        # 时间轴
│   │   ├── blog/
│   │   │   ├── index.astro       # 博客总列表（搜索+筛选）
│   │   │   └── [...slug].astro   # 文章详情页
│   │   └── section/
│   │       └── [name].astro      # 板块文章列表
│   │
│   ├── components/               # UI 组件
│   │   ├── Hero.astro            # 首页 Hero + Canvas 粒子背景
│   │   ├── ParticleBackground.ts # Canvas 粒子动画引擎
│   │   ├── FeaturedSlider.astro  # 精选博客横向自动滑动
│   │   ├── FeaturedCard.astro    # 滑动区单张卡片
│   │   ├── ResumeSection.astro   # 简历/个人介绍区
│   │   ├── ArticleGridCard.astro # 板块内 2×2 文章卡片
│   │   ├── SectionBlock.astro    # 单个板块区块（已废弃，保留参考）
│   │   ├── Nav.astro             # 顶部导航栏
│   │   ├── Footer.astro          # 页脚
│   │   ├── SearchModal.astro     # 全站搜索弹窗
│   │   ├── BlogCard.astro        # 博客列表卡片
│   │   ├── BlogList.astro        # 博客列表容器
│   │   ├── SearchFilter.astro    # 博客页搜索+板块筛选
│   │   └── TableOfContents.astro # 文章目录侧栏（自动高亮）
│   │
│   ├── content/blog/             # 博客文章（按板块分文件夹）
│   │   ├── 项目作品/             # 项目相关文章
│   │   ├── 技术探索/             # 技术、AI、教程
│   │   ├── 阅读笔记/             # 读书笔记、经济学
│   │   └── 闲隅拾笺/             # 诗歌随笔
│   │
│   ├── content.config.ts         # 文章 frontmatter 字段定义
│   ├── data/sections.ts          # 四个板块的名称和颜色
│   ├── layouts/BaseLayout.astro  # 全局页面布局壳
│   ├── styles/global.css         # 全局样式 + 配色变量
│   └── utils/
│       ├── blog.ts               # 文章数据工具函数
│       └── remark-strip-raw.mjs  # 剥离 Hexo 旧标签插件
│
├── public/                       # 静态文件（直接复制到构建产物）
│   ├── CNAME                     # 域名 lt-ieng.cn
│   └── favicon.svg               # 网站图标
│
├── scripts/
│   └── new-post.js               # 交互式新建文章脚本
│
├── astro.config.mjs              # Astro 配置
├── package.json                  # 依赖声明
├── tsconfig.json                 # TypeScript 配置
├── .github/workflows/deploy.yml  # GitHub Actions 自动部署
└── dist/                         # 构建产物（只存在于本地/CI）

数据流

文章 .md → Content Collections → 页面 .astro → 构建 → dist/ → GitHub Pages
                                          ↑
                         组件 .astro（UI 积木）

四、初次访问指引

首页各部分说明

从上往下滚动：

区域	内容	交互
Hero	Canvas 粒子背景 + 名称 + 副标题	粒子随鼠标移动
精选轮播	6 篇 `featured: true` 的文章卡片	自动横向滑动，hover 暂停
简历区	个人介绍 + 技能标签 + 社交链接	静态展示
板块 01-04	四个板块各占全屏，2×2 文章网格	向下滚动时卡片堆叠切换
页脚	版权 + ICP 备案 + 建站信息	静态展示

导航栏

菜单项	功能
首页	回到首页
博客	全部文章列表，支持搜索和板块筛选
时间轴	按年份归档所有文章
关于	关于作者和本站
🔍	搜索弹窗（快捷键 `Ctrl+K`）

各页面说明

URL	内容
`/`	首页
`/blog`	文章总列表
`/blog/板块名/文章slug`	文章详情
`/section/板块名`	某板块的所有文章
`/archives`	按年份时间轴
`/about`	关于页面

五、写作与发布

快速新建文章

npm run new

交互式问答流程：

输入文章标题
选择所属板块（1-4）
输入标签（逗号分隔，如 AI, 教程）
输入一句话摘要（可选）
是否加到首页精选轮播？（featured）
是否置顶到板块四宫格？（pinned）

脚本会在正确的板块文件夹下自动生成带完整 frontmatter 的 .md 文件。

手动新建

在 src/content/blog/对应板块/ 下新建 .md 文件，文件名即 URL slug，建议英文 + 序号前缀：

src/content/blog/技术探索/007-my-post.md
→ URL: /blog/技术探索/007-my-post

Frontmatter 完整参考

---
title: 文章标题                    # 必填
date: 2026-07-15                   # 必填，YYYY-MM-DD
updated: 2026-07-20                # 可选，最后修改日期
section: 技术探索                  # 必填，四选一
tags: [标签1, 标签2]               # 可选，数组格式
cover: https://...                 # 可选，文章封面图（卡片展示用）
hero: https://...                  # 可选，文章页顶部全宽横幅
description: 一句话摘要             # 可选，卡片和搜索结果展示
featured: true                     # 可选，首页精选轮播
pinned: true                       # 可选，板块四宫格置顶
toc: false                         # 可选，关闭目录侧栏
---

Frontmatter 字段速查

字段	类型	默认	说明
`title`	string	—	文章标题
`date`	date	—	发布日期
`updated`	date	同 date	最后修改日期
`section`	enum	—	项目作品 / 技术探索 / 阅读笔记 / 闲隅拾笺
`tags`	string[]	`[]`	标签列表，用于搜索
`cover`	string	无	封面图 URL，卡片展示用
`hero`	string	无	文章页顶部全宽横幅图
`description`	string	无	摘要，卡片和搜索结果用
`featured`	boolean	false	首页精选轮播
`pinned`	boolean	false	板块四宫格置顶
`toc`	boolean	true	是否显示目录侧栏

Markdown 能力

标准 Markdown（标题、列表、链接、图片、表格、引用块）
粗体、斜体、行内代码
代码块自动语法高亮
LaTeX 数学公式： $E=mc^2$ （行内）或 $$...$$（块级）
分隔线 ---（诗歌节间使用）
图片支持外链 URL

发布流程

npm run build          # 构建，检查无报错
git add .              # 暂存所有更改
git commit -m "新文章"  # 提交
git push               # 推送 → GitHub Actions 自动部署

推送后约 1-2 分钟，网站自动更新。

六、调整界面样式

改配色

编辑 src/styles/global.css，修改 @theme 块中的 CSS 变量：

@theme {
  --color-cream: #faf8f5;              /* 页面主背景 */
  --color-warm-white: #f5f0ea;         /* 暖白 */
  --color-ink: #1a1a2e;               /* 主文字 */
  --color-ink-light: #6b7280;          /* 次要文字 */
  --color-gold: #c4a882;               /* 点缀色 */
  --color-gold-light: #d4bea0;         /* 浅点缀色 */
  --color-code-bg: #f0ece6;            /* 代码块背景 */

  /* 四个板块主题色 */
  --color-section-project: #c4a882;    /* 项目作品 */
  --color-section-tech: #5b7a8c;       /* 技术探索 */
  --color-section-reading: #b8937a;     /* 阅读笔记 */
  --color-section-notes: #8b9d83;      /* 闲隅拾笺 */
}

改字体

换字体：编辑 src/layouts/BaseLayout.astro，修改 Google Fonts 的 <link> 标签，然后在 src/styles/global.css 的 @theme 中改对应的 --font-* 变量。

中文字体：建议用系统自带字体栈避免额外加载，如 "Noto Serif SC", "Source Han Serif SC", serif。

改 Hero 背景

编辑 src/components/Hero.astro，找到 .hero 的 background 属性：

.hero {
  background: radial-gradient(ellipse 80% 60% at 50% 35%, #fcfaf7 0%, #f5f0ea 40%, #e8e1d5 100%);
}

改粒子效果

编辑 src/components/ParticleBackground.ts：

参数	默认值	说明
`maxParticles`	120 / 50	桌面/移动端粒子数量
`connectionDist`	130	粒子连线距离（px）
`mouseRadius`	180	鼠标吸引半径（px）

改个人介绍

编辑 src/components/ResumeSection.astro，修改文字、标签、社交链接。

改板块名称/颜色

编辑 src/data/sections.ts，修改 name、color、description。

改导航菜单

编辑 src/components/Nav.astro，修改 pages 数组。

改页脚

编辑 src/components/Footer.astro，修改 ICP 备案号、版权信息等。

七、本地开发与部署

环境要求

Node.js 18+
npm

命令速查

命令	说明
`npm install`	安装依赖（首次或依赖变更后）
`npm run dev`	启动开发服务器 → http://localhost:4321
`npm run build`	构建生产版本 → dist/
`npm run preview`	本地预览生产版本
`npm run new`	交互式新建文章

构建产物

npm run build 后 dist/ 目录结构：

dist/
├── index.html
├── about/index.html
├── archives/index.html
├── blog/
│   ├── index.html
│   ├── 项目作品/005-ai-ad-helper/index.html
│   └── ...
├── section/
│   ├── 项目作品/index.html
│   └── ...
├── CNAME
├── favicon.svg
├── sitemap-index.xml
└── _astro/            # JS/CSS 资源文件

总大小约 1.5MB，14+ 个 HTML 页面。

自动化部署流程

开发者 git push → GitHub Actions 触发
  → checkout 代码
  → npm ci（安装依赖）
  → npm run build（构建）
  → 上传 dist/ 到 GitHub Pages
  → lt-ieng.cn 更新

配置文件：.github/workflows/deploy.yml

八、项目文件地图

想改某个东西时，找哪个文件

你想做什么	编辑哪个文件
写新文章	`npm run new` 或在 `src/content/blog/板块名/` 新建 `.md`
改配色	`src/styles/global.css`
改字体	`src/layouts/BaseLayout.astro` + `src/styles/global.css`
改首页 Hero	`src/components/Hero.astro`
改 Canvas 粒子	`src/components/ParticleBackground.ts`
改精选滑动卡片样式	`src/components/FeaturedCard.astro`
改精选滑动速度	`src/components/FeaturedSlider.astro`
改个人介绍	`src/components/ResumeSection.astro`
改板块名称/颜色	`src/data/sections.ts`
改板块卡片样式	`src/components/ArticleGridCard.astro`
改导航菜单	`src/components/Nav.astro`
改搜索弹窗样式	`src/components/SearchModal.astro`
改博客列表卡片	`src/components/BlogCard.astro`
改文章详情页布局	`src/pages/blog/[...slug].astro`
改文章目录样式	`src/components/TableOfContents.astro`
改页脚/ICP号	`src/components/Footer.astro`
改关于页	`src/pages/about.astro`
改文章 frontmatter 字段	`src/content.config.ts`
改 Astro 站点配置	`astro.config.mjs`
改部署流程	`.github/workflows/deploy.yml`
改域名	`public/CNAME`
改网站图标	`public/favicon.svg`
改新建文章脚本	`scripts/new-post.js`

九、常见问题

Q: 文章渲染出来是纯文本不是 HTML？

确认 @tailwindcss/typography 已安装（npm install @tailwindcss/typography），且在 src/styles/global.css 中有 @plugin "@tailwindcss/typography";。

Q: 搜索弹窗样式不生效？

搜索结果是 JS 动态生成的，CSS 用了 is:global 确保 scoped 样式能匹配。如果改样式没效果，检查 src/components/SearchModal.astro 的 <style> 是否带 is:global。

Q: 标签在文章里显示出来了？

这是 Hexo 旧文章的 Nunjucks 标签。已在构建时通过 remark-strip-raw.mjs 插件自动剥离。新文章不需要这个标签。

Q: 精选卡片滑动时 hover 错位？

hover 时动画会完全暂停（animationPlayState: paused），卡片原地不动。如果还有问题，清浏览器缓存后重试。

Q: 诗歌节间距太小？

用 ---（分隔线，渲染为 <hr>）而不是空行来分隔诗歌节。Markdown 会把多个空行合并为一个段落间距。

Q: 怎么关掉某篇文章的目录侧栏？

在 frontmatter 中写 toc: false。

Q: 怎么让文章在首页精选轮播里出现？

在 frontmatter 中写 featured: true，最多选 6 篇。

Q: 怎么让文章出现在板块四宫格？

在 frontmatter 中写 pinned: true。pinned 文章优先展示，不够 4 篇自动用最新文章补位。

Q: 构建失败怎么办？

看终端报错信息，通常提示具体文件和行号
检查最近改动的 .md 文件 frontmatter 格式是否正确
运行 npm run dev 看开发模式是否有同样的错误
date 字段必须用 YYYY-MM-DD 格式
section 字段必须是四个值之一
tags 必须用数组格式 [标签1, 标签2]