建站笔记：三站架构、怎么改、怎么编译、怎么在本地看¶

配套阅读：本文是博客引擎的选择 →、Hugo 从零搭建 →、GitHub Pages 分支区别 → 的「实操手册」版。前面几篇讲「为什么选」，这篇讲「怎么动手」。

我目前手上有三个站点，分别用两种引擎搭建，现在都并排在 wild-civil/ 工作区里统一管理。这篇文章把它们的目录结构、改哪里、怎么编译、怎么在本地看一次讲清，免得我自己过段时间也忘了。

一、总览：我手里的三个站¶

站点	引擎	仓库目录	线上地址	部署方式	Pages 源（分支）
civil_nav	Hugo 0.147.7	`civil_nav/`	nav.hanvon.top	GitHub Actions 自动	`gh-pages`（项目页）
civil_works	Hugo 0.147.7	`civil_works/`	works.hanvon.top	GitHub Actions 自动	`gh-pages`（项目页）
Civil_Blog	Hexo 5.4.2	`Civil_Blog/`	blog2.hanvon.top	手动 `hexo d`	`main`（用户页）

几个要点先说清楚：

nav / works 是「项目页」：仓库名不是 <user>.github.io，所以 GitHub 默认从 gh-pages 分支 serve；每次 git push 触发 Actions 自动构建。
Civil_Blog 是「用户页」：它的线上仓库名就是 wild-civil.github.io，所以成品直接回写到 main 分支，靠 hexo d 手动推送（仓库里没有 Actions 工作流，只有 dependabot.yml）。这正好对应我之前写的「用户页成品就是 main」。
三站现在在同一个 wild-civil/ 工作区并排，引擎不同但一起管；nav 已经把 Blog 链进去了，访问体验上已经「放进来」。

二、civil_nav —— Hugo 导航站¶

2.1 目录结构¶

civil_nav/
├── config.toml            # 站点标题、baseURL、顶栏参数（wiki/github 链接）
├── data/links.yaml        # ★ 内容数据：分区 + 卡片（平时只改这里）
├── layouts/index.html     # 整页模板（Webstack 风格：左侧固定栏 + 右侧卡片网格）
├── static/                # 原样拷到站点根目录
│   ├── CNAME              # 自定义域名文件（nav.hanvon.top）
│   └── assets/            # CSS / JS / 字体 / 图片（xenon 主题资源）
├── content/_index.md      # 首页桩文件（仅 frontmatter，无正文）
├── .github/workflows/ci.yml
└── .gitignore

2.2 怎么改¶

加 / 改链接：只编辑 data/links.yaml，不用碰模板。结构如下（我现在填了 3 个分区：Civil's Nav / 友链 / 常用工具）：

sections:
  - title: Civil's Nav       # 分区标题
    icon: star               # 分区图标（FontAwesome 4.7 名字，不含 fa- 前缀）
    items:
      - name: Wiki 知识库     # 卡片标题
        desc: 我的学习笔记与知识库
        url: https://wiki.hanvon.top
        # icon: https://.../logo.png   # 可选：不填就自动用该域名的 favicon

卡片图标默认按 url 域名用 Google Favicon 服务自动取；想强制用某张图，就填 icon:。

改站名 / 副标题 / 页脚 / 顶栏链接：编辑 config.toml 的 title、params.subtitle、params.footer、params.wiki、params.github。
换图标（favicon / logo）：替换 static/assets/images/favicon.png、logo@2x.png 等，或改 layouts/index.html 里对应的 <img src>。
改样式：编辑 static/assets/css/nav.css（白卡 + hover 上浮）或 xenon 系列 CSS；一般不用动 layouts/index.html。

2.3 本地编译¶

cd civil_nav
D:/tools/hugo/hugo.exe --minify      # 生成 public/

产物在 public/：根目录有 index.html、CNAME、assets/。

2.4 本地预览¶

实时预览（推荐，改文件自动刷新）：

D:/tools/hugo/hugo.exe server --bind 127.0.0.1 --port 1313
# 浏览器打开 http://127.0.0.1:1313/

纯静态看：先 hugo --minify 生成 public/，再起一个静态服务器（不要直接双击 file:// 打开，原因见第六节）：

cd public && python -m http.server 8080
# 浏览器打开 http://127.0.0.1:8080/

2.5 部署¶

git add -A && git commit -m "update nav" && git push

push 后 GitHub Actions（ci.yml）自动 hugo --minify 并推到 gh-pages，GitHub Pages 重新发布。

三、civil_works —— Hugo 作品集¶

套路和 nav 完全一样（都是 Hugo 单页站），这里只列差异。

3.1 目录结构¶

civil_works/
├── config.toml
├── data/projects.yaml      # ★ 内容：分类 + 项目
├── layouts/index.html      # 筛选网格（filterSelection 脚本驱动按钮）
├── static/
│   ├── CNAME
│   ├── favicon.svg         # 站点图标（复用 wiki 的书本 logo）
│   └── assets/index.css, index.js
└── .github/workflows/ci.yml

3.2 怎么改¶

加 / 改作品：编辑 data/projects.yaml。categories 是顶部筛选按钮，items 是卡片：

categories: [MCU, Linux, Sensor, Power]   # 顶部筛选按钮，按需增删

items:
  - name: 项目名
    desc: 一句话简介
    categories: [MCU]        # 可多个，决定被哪些按钮筛出
    website: https://...      # 可选：作品主页
    repo: https://github.com/...   # 可选：源码仓库
    image: /images/xxx.png    # 可选：封面图（放 static/images/ 或外链）

加封面图：把图放进 static/images/，再在 yaml 写 image: /images/xxx.png；也可以直接填外链 image: https://.../xxx.png。
换图标 / 样式：同上，替换 static/favicon.svg 或改 static/assets/index.css。

3.3 本地编译与预览¶

同 nav：hugo --minify 出 public/；hugo server 实时预览。筛选按钮在本地一样可用。

3.4 部署¶

同 nav：git push → Actions → gh-pages。

四、Civil_Blog —— Hexo 博客（用户页）¶

4.1 目录结构¶

Civil_Blog/
├── _config.yml             # 站点配置（title / url / 部署 / permalink）
├── _config.butterfly.yml   # 主题配置（butterfly 主题专属）
├── source/
│   ├── _posts/             # ★ 文章（27 篇 .md，按 001~027 编号）
│   ├── images/             # 文章图片
│   ├── css/ js/            # 自定义样式 / 脚本
│   ├── categories/ tags/ link/   # 分类 / 标签 / 友链页
│   └── CNAME               # blog2.hanvon.top
├── themes/
│   ├── butterfly/          # 当前启用的主题（在 _config.yml 里 theme: butterfly）
│   └── landscape/          # 也装了但没启用
├── scaffolds/              # 新建文章模板（post.md / page.md / draft.md）
├── node_modules/           # 依赖已装（含 hexo 可执行）
└── package.json            # 脚本：clean / generate / deploy / server

注意：仓库里没有 .github/workflows/ci.yml，所以不自动部署，靠手动 hexo d。

4.2 怎么改¶

写新文章：

cd Civil_Blog
npx hexo new "文章标题"     # 在 source/_posts/ 生成「文章标题.md」（按 scaffolds/post.md 模板）

或直接新建 source/_posts/xxx.md，front-matter 至少要有 title:、date:、tags:、categories:。我现在那 27 篇文章就是这种 .md。

改站点信息：编辑 _config.yml（title、subtitle、author、url；permalink 用了 abbrlink 算法生成短链）。
改主题外观：编辑 _config.butterfly.yml——这是 butterfly 的专属配置，比改 _config.yml 更常用（配色、首页、菜单、侧栏、友链大多在这里）。
改导航 / 侧栏 / 友链：butterfly 多用 _config.butterfly.yml 的 menu，或 source/_data/*.yml（如 link.yml、widget.yml）。
加图片：丢进 source/images/，文章里用 ![说明](/images/xxx.png) 引用，构建后随站发布。

4.3 本地编译¶

Hexo 的核心命令（你在对话里也提到过）：

cd Civil_Blog
npx hexo clean        # 清空 public/ 与缓存 db.json（排错第一步）
npx hexo generate     # 生成 public/（等价 hexo g）

hexo clean 在改了主题配置或遇到缓存错乱时很关键；平时只改文章直接 hexo g 就行。

4.4 本地预览¶

实时预览（推荐）：

npx hexo server      # 默认 http://localhost:4000 ，改文件自动刷新
# 想连草稿一起看：hexo s -d

纯静态看：hexo g 出 public/，再起静态服务器：

cd public && python -m http.server 8080
# 浏览器打开 http://127.0.0.1:8080/

4.5 部署（手动）¶

npx hexo deploy        # 等价 hexo d；按 _config.yml 的 deploy 配置推送

_config.yml 里已经配好：

deploy:
  type: git
  repository: https://github.com/wild-civil/wild-civil.github.io.git
  branch: main

所以 hexo d 把 public/ 推到用户页仓库的 main——这就是前面说的「用户页成品就在 main」。source/CNAME（blog2.hanvon.top）构建后自动落到 public/ 根，GitHub Pages 据此绑定自定义域名。

想也给它接 CI 自动部署？可以参考我写的从零搭建多站点 MkDocs →，给 Civil_Blog 加一个 hexo g + actions-gh-pages 的工作流。但用户页默认就是 main，直接 hexo d 最简单，所以我目前保留手动部署。

五、命令对照表（Hugo vs Hexo）¶

目的	Hugo（nav / works）	Hexo（Civil_Blog）
清理缓存	（一般无需；必要时删 `resources/` 或 `hugo --gc`）	`hexo clean`
生成静态站	`hugo` / `hugo --minify`	`hexo generate` / `hexo g`
本地实时预览	`hugo server`	`hexo server` / `hexo s`
部署上线	`git push`（Actions 代劳编译+发布）	`hexo deploy` / `hexo d`（手动推送到 git）
新建内容	手写 `data/*.yaml` 或 `.md`	`hexo new "标题"`

核心区别一句话：Hugo 站是「数据驱动 + CI 自动部署」；Hexo 站是「文章驱动 + 手动 hexo d 部署」（用户页机制决定了回写 main）。

六、关于「本地静态显示」的两个坑¶

别直接双击 public/index.html 用 file:// 打开。 nav / works 的 baseURL 是真实域名，生成的资源路径是绝对路径（如 /assets/css/...）。file:// 下浏览器会把 / 当成磁盘根，结果 CSS / JS 全部 404，页面「裸奔」。正确做法是用 hugo server 或 python -m http.server（从 public/ 目录起服务）。
Hexo 同理。 尤其开了绝对资源路径或 abbrlink 短链后，直接 file:// 也可能缺资源。统一用 hexo s 或 python -m http.server 最稳。

一句话：本地看效果，要么用引擎自带的 server，要么用 python -m http.server 起一个真·HTTP 服务；别用 file:// 直接开 public/。

七、小结¶

nav / works（Hugo）：改 data/*.yaml → hugo server 本地看 → git push 上线（Actions 编译到 gh-pages 项目页）。
Civil_Blog（Hexo）：写 source/_posts/*.md → hexo s 本地看 → hexo clean && hexo g && hexo d 上线（手动回写用户页 main）。
三站现在都在 wild-civil/ 工作区，引擎不同但并排管理；nav 已经把 Blog（Hexo）链进去了，访问体验上已经「放进来」了。

如果你也想像 nav / works 那样「push 就自动部署」，我可以给 Civil_Blog 补一个 GitHub Actions 工作流——只要说一声。