从零搭建 boyuan.net.cn：Astro + Firefly + 宝塔 Nginx 全流程

一、项目准备#

1
node -v   # v26.7.0
2
npm -v    # 11.19.0

1
src/content/posts/     文章目录（最常用）
2
src/content/spec/      关于、友链、留言等特殊页面
3
src/config/            站点配置
4
public/                静态资源，原样拷贝到 dist
5
dist/                  构建产物，部署的就是这个目录
6
package.json           项目脚本

二、配置站点信息#

站点的大部分基础信息都在 src/config/siteConfig.ts 里：

1
export const siteConfig: SiteConfig = {
2
  title: "石以砥焉化钝为利",
3
  subtitle: "以石自砥 · 化钝为利",
4
  site_url: "https://boyuan.net.cn",
5
  themeColor: { hue: 210, defaultMode: "system" },
6
  siteStartDate: "2026-09-20",
7
};

这里几个容易踩的点：

• site_url 必须写最终域名，RSS、sitemap、OpenGraph 全都依赖它。写错了分享出去的链接就是错的。
• themeColor.hue 是主题色相，0 到 360。本站用 210，偏冷的钢青色。
• siteStartDate 用于页脚统计”已运行多少天”。

导航菜单在 src/config/navBarConfig.ts，个人信息和社交链接在 src/config/profileConfig.ts，首页横幅的文字和壁纸在 src/config/backgroundWallpaper.ts。

页面开关集中在 siteConfig.ts 顶部的 pages 里，关掉的页面会返回 404 并自动从导航栏隐藏：

1
const pages = resolvePageToggles({
2
  friends: true,      // 友链
3
  guestbook: true,    // 留言板
4
  dynamic: true,      // 动态
5
  projects: true,     // 项目
6
  gallery: false,     // 相册（放好照片再开）
7
  booknav: true,      // 书签导航
8
  bilibili: true,     // 追番
9
  sponsor: false,     // 打赏（没放收款码就别开）
10
});

三、写文章#

文章用 Markdown，放在 src/content/posts/。最简单的形式是一个 .md 文件：

1
---
2
title: 文章标题
3
published: 2026-09-20
4
description: 文章简介，会显示在列表和分享卡片里
5
image: ./cover.avif
6
tags: [博客搭建, Astro]
7
category: 博客指南
8
draft: false
9
---
10

11
这里开始写正文。

需要配图时，改成一个文章一个目录：

1
src/content/posts/build-my-blog/
2
├── index.md      正文
3
├── cover.avif    封面
4
└── step-1.png    正文插图

正文里直接引用同目录图片：

1
![部署截图](./step-1.png)

1
return import.meta.env.PROD ? data.draft !== true : true;

四、本地运行#

1
npm install       # 安装依赖，首次约 3 分钟
2
npm run dev       # 开发服务器，默认 http://localhost:4321/

开发服务器有热更新，改配置和文章都会自动刷新。

五、生产构建#

1
npm run build

这个命令不是只跑 Astro，它会按顺序做一串事情：

构建完成后，产物在 dist/。部署到服务器的就是这个目录里的内容。

1
npm run preview

六、服务器环境#

线上是宝塔面板 + Nginx，boyuan.net.cn 和 www.boyuan.net.cn 指向同一个网站根目录。

Nginx 配置里核心就三行：

1
root /www/wwwroot/boyuan.net.cn;
2
index index.html;
3

4
location / {
5
    try_files $uri $uri/ $uri.html =404;
6
}

try_files 最后那个 $uri.html 很关键。Astro 默认输出 about.html 这样的文件而不是 about/index.html，不加上这条，直接访问 /about/ 就会 404。

HTTPS 证书由宝塔申请和管理，部署静态文件时不要动证书配置。

七、部署流程#

思路很简单：

1. 本地执行 npm run build
2. 把 dist 打包上传到服务器
3. 备份旧的网站目录
4. 清空网站根目录里的旧静态文件
5. 解压新的 dist 到网站根目录
6. 检查 Nginx 配置并 reload

八、线上验证#

部署完成后按顺序检查这几项：

1
https://boyuan.net.cn/                      首页能打开 → Nginx root 和静态文件没问题
2
https://boyuan.net.cn/rss.xml               RSS 正常 → 文章元数据构建成功
3
https://boyuan.net.cn/_astro/               资源能访问 → 资源路径没问题

如果样式或下拉菜单还是旧状态，先强制刷新：

1
Ctrl + F5

仍然不对，就去比对线上 HTML 里引用的资源文件名，是不是最新一次构建生成的。

九、日常更新#

以后发新文章的固定流程：

1. 在 src/content/posts/ 新建 Markdown 或文章目录
2. 设置好 published、tags、category、draft
3. 本地 npm run dev 预览
4. 确认无误后 npm run build
5. 上传新的 dist
6. 访问线上确认

小结#

整条链路可以概括成一句话：

用 Markdown 写内容，用 Astro 生成静态站点，用宝塔 Nginx 托管 dist，用 HTTPS 把它稳定地挂到 boyuan.net.cn。

它不是最复杂的部署方式，但对个人博客来说很舒服：本地写作足够快，线上访问足够轻，出问题也容易定位。 后面无论是加文章、加工具体验、改导航、换壁纸，基本都能围着这套流程继续迭代。