前言：为什么选择 Astro？

Astro 作为新一代的静态站点生成器，凭借其独特的「组件优先」理念和「零 JS 默认输出」特性，成为搭建内容型网站的理想选择。相较于传统方案，Astro 具有以下优势：

  • 极致的加载性能（默认生成纯静态 HTML）
  • 灵活的组件体系（支持 React/Vue/Svelte 组件）
  • 内容驱动的开发模式
  • 完善的 Markdown 支持
  • 轻量级架构（项目依赖仅约 100KB）

一. 准备工作

1.1 环境准备

  • npm 9+ 或 pnpm 7+

  • Node.js（推荐 v18+）

点击下载：Node.js v22.13.1 长期支持版本

  • 推荐使用 VS Code 编辑器
1
2

node -v
# 检查版本

1.2 clone 主题到本地

区别于 Hexo，Astro 框架并不能做到在配置文件里更改主题即可实现换主题的效果，而是需要将整个项目文件更换：即主题文件为项目文件本身。故事先选定好主题便是重中之重，以下列出部分笔者比较喜欢的主题，以便读者参考

fuwari

Koibumi

astro-blur

将主题 clone 到本地

1

git clone git@github.com:saicaca/fuwari.git #以fuwari为例

1.3 安装依赖

1
2

pnpm install
pnpm add sharp

此时网页就可以在本地跑起来了，启动本地服务器：

1
2

npm run dev
# 访问 http://localhost:4321

在浏览器输入 http://localhost:4321 访问网页

二. 主题配置

2.1 文件结构说明（以 fuwari 主题为例）

1
2
3
4
5
6
7

src/
  content/
    config.ts      # 博客配置
    blog/          # 文章目录（示例文章）
  layouts/
    PostLayout.astro  # 文章布局
 /

2.2 修改配置文件

编辑配置文件 src/config.ts 以自定义博客，在博客本地服务器运行时可以是可以修改文件的，修改效果将会实时刷新在本地网页上

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

import type {
  LicenseConfig,
  NavBarConfig,
  ProfileConfig,
  SiteConfig,
} from './types/config'
import { LinkPreset } from './types/config'

export const siteConfig: SiteConfig = {
  title: 'Fuwari', // 网站标题
  subtitle: 'Demo Site', // 网站描述
  lang: 'en', // 语言选择'en', 'zh_CN', 'zh_TW', 'ja', 'ko', 'es', 'th'
  themeColor: {
    hue: 250, // 主题颜色的默认色调，从0到360。例如，红色：0，青色：200，青色：250，粉红色：345
    fixed: false, // 是否为访问者隐藏主题颜色选择器
  },
  banner: {
    enable: false, //是否开启横幅
    src: 'assets/images/demo-banner.png', // 横幅路径:相对于/src的路径，如果相对于/public路径则应以'/'开头
    position: 'center', // 横幅图展示的位置，支持的值:'top', 'center', 'bottom','center'是默认选项
    credit: {
      enable: false, // 是否在在横幅图像上显示横幅署名文本
      text: '', // 在横幅图像上显示的署名文本
      url: '', // (可选项) 原作品或作者的链接页面
    },
  },
  toc: {
    enable: true, // 是否在博客右侧显示目录
    depth: 2, // 设置目录中显示的标题最大深度（可选范围：1至3级）
  },
  favicon: [
    // 如果使用默认网站图标此项请留空
    // {
    //   src: '/favicon/icon.png',    // 网站图标的路径，相对于/public目录
    //   theme: 'light',              // (可选项) “亮”或“暗”，仅当图标目录下存在不同亮暗图标时方可设置
    //   sizes: '32x32',              // (可选项) 图标大小, 仅当图标目录下存在不同大小图标时方可设置
    // }
  ],
}

export const navBarConfig: NavBarConfig = {
  links: [
    LinkPreset.Home,
    LinkPreset.Archive,
    LinkPreset.About,
    {
      name: 'GitHub',
      url: 'https://github.com/saicaca/fuwari', // 内部链接不应包含基本路径，因为是自动添加的
      external: true, // 显示外部链接图标，并可在新标签页中打开
    },
  ],
}

export const profileConfig: ProfileConfig = {
  avatar: 'assets/images/demo-avatar.png', // 头像路径:相对于/src的路径，如果相对于/public路径则应以'/'开头
  name: 'Lorem Ipsum', // 名字
  bio: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.', // 简介
  links: [
    {
      name: 'Twitter',
      icon: 'fa6-brands:twitter', // 访问https://icones.js.org/以获取图标代码
      // 如果尚未包含相应的图标集，则需要安装该图标集
      // 指令为：pnpm add @iconify-json/<图标集名称>
      url: 'https://twitter.com', // 图标的自定义链接
    },
    {
      name: 'Steam',
      icon: 'fa6-brands:steam',
      url: 'https://store.steampowered.com',
    },
    {
      name: 'GitHub',
      icon: 'fa6-brands:github',
      url: 'https://github.com/saicaca/fuwari',
    },
  ],
}

export const licenseConfig: LicenseConfig = {
  enable: true,
  name: 'CC BY-NC-SA 4.0',
  url: 'https://creativecommons.org/licenses/by-nc-sa/4.0/', // 创作共用许可协议
}

三. 托管网页到云端

3.1 选择网站托管平台

构建并部署你的 Astro 站点需要选择一个可靠的静态网页托管平台，例如AWS S3 静态网站托管，Vercel 和 Cloudflare 等等

本文使用Vercel 作为示例，其余平台的部署教程可在 Astro 官方文档：Astro Docs下找到

使用以下 astro add 命令为你的 Astro 项目中添加 Vercel 适配器 以开启 SSR。此命令将安装适配器并同时自动对你的 astro.config.mjs 文件进行适当的配置：

1

npx astro add vercel

3.2 上传项目文件到 Github

  • 如果你有 git 工具
1
2
3
4
5
6

git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin 你的仓库地址
git push -u origin main
  • 或者直接使用 Vscode 或者 Github Desktop 提交

3.3 部署到 Versel 进行托管

  • 注册一个Vercel 账号
  • 选择右侧 Add New，创建一个新的 Project
  • 登陆自己的 Github 账号，import 导入博客项目库
  • 设置好项目名称（项目名称会是 Vercel 分发给你的子域名的一部分，例如 https://项目名称.vercel.app/）
  • Deploy 然后耐心等待
  • 网页托管完成之后立马就可以登陆了

修改博客文件只要同步到 Github 仓库即可，Vercel 会自动同步刷新你的博客页面

四. 绑定域名（可选项）

可能你觉得 https://项目名称.vercel.app/ 太难看了或是国内访问 Vercel 并不稳定，那么可以自己购入域名进行自定义

Vercel 支持添加自定义域名进行重定向

域名购买：腾讯云域名

​阿里云万网

  • 选择 Vercel 中博客项目打开 Settings
  • 选择 Domain 并进行 Add
  • 输入你填写的域名，默认设置即可
  • 前往域名购买商域名控制台为域名添加解析：

对应 Vercel 提示 Type 填入对应的值，回来刷新 Vercel 的 Domain 设置，显示 Valid Configuration 即可

注：购买域名之后需要一定的 DNS 解析时间，Vercel 中显示未能配置成功时可耐心等待

五. 生态推荐

  • 官方工具：
    • Starlight（文档模板）
    • Astro DB（数据库集成）
  • 社区插件：
    • astro-seo：SEO 优化
    • astro-robots-txt：机器人协议
    • astro-compress：资源压缩
  • 学习资源：
    • 官方文档：https://docs.astro.build
    • 示例仓库：https://github.com/withastro/astro/examples
    • 社区模板：https://astro.build/themes

通过本指南，您已经掌握了从零搭建 Astro 博客的核心技能。接下来可以：

  1. 尝试接入 CMS 内容管理系统
  2. 开发自定义组件库
  3. 探索 Astro Islands 的深度应用
  4. 参与开源社区贡献