今天把本地博客从一个最小可用的 Astro 版本，整理成了适合正式部署的结构，并进一步切换到了 Fuwari 主题。整个过程的重点不只是把页面跑起来，而是把目录、构建方式和后续写作方式一起固定下来，这样后面维护会轻松很多。
这次最终采用的方案
现在的博客结构可以概括成三层：
- 用
Astro负责内容组织和静态页面生成。 - 用
Fuwari提供博客主题、归档、搜索、RSS 和整体样式。 - 用
Docker Compose + Nginx作为生产部署方式。
这样拆开的好处是很明确的。Astro 负责生成静态文件，Nginx 只负责托管这些静态文件，运行时足够简单；而主题层则由 Fuwari 提供，不需要自己从零写页面结构。
现在的目录布局
当前最重要的目录是这些：
WechatWorkspace/├── astro-blog/│ ├── src/│ │ ├── content/│ │ │ ├── posts/│ │ │ └── spec/│ │ ├── components/│ │ ├── layouts/│ │ ├── pages/│ │ └── config.ts│ ├── public/│ ├── Dockerfile│ ├── Dockerfile.dev│ ├── astro.config.mjs│ ├── package.json│ └── pnpm-lock.yaml├── docker-compose.yml└── docker-compose.dev.yml这里面最关键的是：
astro-blog/src/content/posts/以后新文章都放这里。astro-blog/src/config.ts管站点标题、简介、头像、导航栏和主题色。docker-compose.yml生产版启动方式。docker-compose.dev.yml开发预览方式。
这次安装和改造的流程
1. 先搭一个最小 Astro 博客
一开始先做的是一个很轻的 Astro 站点，只需要文章列表页和文章详情页，目的是先确认现有 Markdown 能正常导入和阅读。
当时的重点不是主题，而是验证两件事：
- 现有 Markdown 能不能顺利迁进去。
- Docker Compose 在本地能不能稳定跑起来。
这样做的好处是，先把内容迁移链路打通，再换主题，问题会少很多。
2. 再切成生产版部署结构
确认内容能跑以后，把部署方式改成了正式一点的模式：
- 构建阶段使用 Node 容器执行
astro build - 输出
dist/ - Nginx 镜像只负责托管
dist/
对应思路就是典型的多阶段构建：
FROM node:20-alpine AS builder# 安装依赖并构建 dist
FROM nginx:1.27-alpine# 复制 dist 到 nginx html 目录这种方式比直接跑 astro dev 更适合服务器，因为：
- 运行时更轻
- 暴露面更小
- 没有开发服务器依赖
- 更接近静态站的标准部署方式
3. 最后切到 Fuwari 主题
后面把博客模板层整体替换成了 Fuwari。
要注意的是，Fuwari 不是简单的“换一套 CSS”，它本身就是一套完整的 Astro 博客模板，包含：
- 自己的内容 schema
- 自己的路由结构
- 搜索功能
- RSS
- 归档页
- 关于页
- 主题配置
所以这一步的正确做法不是零碎拼接，而是：
- 用
Fuwari作为新的模板底座。 - 把原来的文章内容迁移到它的
src/content/posts/。 - 按它要求的 frontmatter 改字段。
- 再把 Docker/Nginx 生产构建接回去。
文章格式现在怎么写
现在文章不是随便一个 Markdown 就能直接识别，必须符合 Fuwari 的 frontmatter 格式。
最常用的最小模板是：
---title: 文章标题published: 2026-04-02description: 一句话描述文章内容tags: [Astro, Docker]category: 建站draft: false---
这里开始写正文。注意几个字段：
title文章标题。published发布时间。description首页和 SEO 描述常用。tags标签列表。category分类。draft如果写成true，生产构建时通常不会出现在正式页面里。
以后文章放哪里
以后新文章统一放在：
astro-blog/src/content/posts/比如你写一篇：
astro-blog/src/content/posts/astro-notes.md最终路径会是：
/posts/astro-notes/如果你放在子目录里，例如：
astro-blog/src/content/posts/docker/nginx.md那路径就会变成：
/posts/docker/nginx/本地预览和生产预览
这次也顺手把开发和生产两种运行方式分开了。
开发模式
开发时更适合用：
docker compose -f docker-compose.dev.yml up --build -d它启动的是 Astro 开发服务器，适合边改边看。
生产模式
正式预览或准备上线时用：
docker compose up --build -d它会：
- 执行
pnpm build - 生成静态文件
- 用 Nginx 对外提供服务
这次踩到的一个小问题
切到 Fuwari 之后，开始时首页里多出了一篇主题自带的演示文章。这个问题不是构建错误，而是因为主题仓库里还有一个默认示例内容目录没有清掉。
这类问题很典型，也提醒了一点：
- 换主题时，除了看
src/content/posts/*.md - 也要检查有没有
src/content/posts/**/index.md这种子目录文章
否则你以为自己只保留了 4 篇文章，结果页面上还会冒出主题自带的内容。
Astro 的几个实用小技巧
1. 先把内容链路打通，再折腾主题
如果一开始就同时换主题、改部署、迁内容，问题会缠在一起。更稳的顺序是：
- 先用最小 Astro 站点确认 Markdown 能正常显示
- 再确定生产部署方式
- 最后再替换成正式主题
这样定位问题非常快。
2. 静态博客尽量用生产构建验证
开发模式只是方便写作，真正决定是否能上线的是生产构建能不能成功。
所以每次改完结构、依赖或主题，最好都跑一次：
docker compose up --build -d只要生产构建能过，基本就说明这次改动是可部署的。
3. frontmatter 要尽量固定
静态博客最怕的不是页面丑，而是文章格式今天一个样、明天一个样。后面一旦多了十几篇、几十篇，就很难统一整理。
比较稳的方法是从一开始就固定模板，例如：
- 标题
- 发布时间
- 描述
- 标签
- 分类
- draft 状态
这样后面自动生成归档、搜索和 RSS 都会更稳定。
4. 主题仓库不要直接当成“黑盒”
像 Fuwari 这种主题本质上是完整项目，不是一个单独样式包。所以接入前最好先确认：
package.jsonsrc/content/config.tssrc/config.tssrc/pages/
这四类文件基本决定了：
- 依赖怎么装
- 文章字段怎么写
- 站点信息在哪改
- 页面路由怎么组织
5. 写博客时把“部署信息”也记进文章
今天这次迁移里最有价值的部分之一，其实不是主题，而是把部署方式也固定进了代码结构。
比如：
- 开发版 Compose
- 生产版 Compose
- Dockerfile
- Nginx 配置
以后就算隔一段时间不碰这个博客，回来时也能很快接上。
这套结构接下来怎么用
后面写文章时，流程可以很简单：
- 在
astro-blog/src/content/posts/新建一个.md - 按固定 frontmatter 填好标题、日期、描述和标签
- 写正文
- 本地预览
- 确认没问题后提交 Git
如果只是写内容，基本不需要再碰页面结构；只有在想改主题风格、导航、SEO 或部署方式时，才需要去动模板层和配置层。
小结
今天这次整理，真正完成的不是“把博客装上”，而是把一套长期可维护的博客工作流定下来了：
- 内容放哪里
- 主题怎么接
- Docker 怎么跑
- Nginx 怎么托管
- Git 怎么留版本切换点
后面无论继续用 Fuwari，还是再换别的 Astro 主题，都已经有了一个比较稳的基础。