前言

作为一名开发者或学习者，拥有一个属于自己的博客不仅可以记录成长、展示作品，还能积累知识。在这篇文章中，我将基于和 ChatGPT 的一次完整对话，总结如何使用 Astro 构建静态博客，并将其成功部署到 GitHub Pages，包括路径配置、图片处理、分支推送、Token 设置等实战细节。

---

1. 为什么选择 Astro？

在众多静态网站生成器中，Astro 是近年来最受欢迎的之一，原因如下：

• 默认使用静态渲染，加载极快

• 支持多种框架组件（React/Vue/Svelte等）

• 支持 Markdown 和 MDX

• 易部署，生态活跃

相比 Hexo、Hugo、11ty，Astro 更现代、更易用，也更符合前端趋势。

---

2. 创建 Astro 博客项目

npm create astro@latest

• 选择博客模板（Blog）

• 安装依赖后运行开发：

npm run dev

打开 http://localhost:4321 查看效果。

---

3. 自定义页面内容

你可以修改：

• 首页内容：src/pages/index.astro

• 关于我页面：src/pages/about.astro 或 about.html.astro

• 博文：src/content/blog/

3.1 关于我页面示例（Markdown）

<Layout
  title="About Me"
  description="Software Engineer & AI Explorer"
  pubDate="2025-04-02"
  heroImage="/blog-placeholder-about.jpg"
>
  <p>
    Hi! I’m Yuxu Ge, a software engineer and AI enthusiast with 10+ years of backend experience.
    I'm currently pursuing an MSc in AI, exploring LLMs, RAG, agents and virtual intelligence.
  </p>
</Layout>

3.2 如果你想生成 /about.html 而不是 /about/index.html：

重命名页面为：

src/pages/about.html.astro

即可生成 dist/about.html

4. 正确处理 Markdown 中的图片

官方推荐方案 ✅：

将图片放在 /public/ 目录中，例如：

public/images/blog/my-post/image.jpg

Markdown 中引用：

![图](/images/blog/my-post/image.jpg)

✅ 编辑器和 Astro 都能正常识别

❌ 不推荐将图片与 .md 同级放在 src/content 中，因为 Astro 不会打包这些图片。

---

5. 使用 gh-pages 部署到 GitHub Pages

安装工具：

npm install --save-dev gh-pages

设置 astro.config.mjs：

如果仓库名是 virtual-velocity，则设置：

export default defineConfig({
  base: '/virtual-velocity/',
});

添加部署脚本：

"scripts": {
  "deploy": "astro build && gh-pages -d dist --branch gh-pages "
}

执行部署：

npm run deploy

---

6. 遇到问题的解决方案汇总

问题	解决方案
sharp 模块缺失	npm install sharp 或改用 squoosh 图像服务
图片路径在编辑器能看但浏览器 404	图片放到 /public/ 并使用绝对路径
构建输出为 /about/index.html 而不是 /about.html	页面命名为 about.html.astro
gh-pages 报“分支已存在”	加 —force
报错连接不上 GitHub 22 端口	改用 HTTPS 远程地址
GitHub 不接受密码推送	使用 Personal Access Token

---

7. GitHub Token 鉴权配置（重要）

GitHub 已禁用密码推送。你需要：

1. 生成 Personal Access Token（classic）

2. 使用 Token 替代密码进行登录推送

或者改用 SSH：

git remote set-url origin [email protected]:yourname/yourrepo.git

---

总结

通过 Astro + GitHub Pages，你可以快速搭建一个现代化、极致简洁又易于维护的个人博客。整合配置后，只需：

npm run deploy

博客就能自动部署上线，真正做到所写即所得。

🌐 示例地址（替换为你自己的）

https://yourname.github.io/your-repo/

---

🔧 配置自定义域名（如 blog.geyuxu.com）

如果你希望用自己的域名（如 blog.geyuxu.com）来访问博客，而不是默认的 GitHub Pages 地址（如 https://yourname.github.io/yourrepo/），可以按照以下步骤进行配置：

---

✅ 1. 在 GitHub 仓库中设置自定义域名

1. 打开你的博客仓库

2. 点击 Settings → Pages

3. 找到 “Custom domain” 输入框

4. 填入你绑定的域名，例如：blog.geyuxu.com

   勾选 “Enforce HTTPS”（建议开启）

---

✅ 2. 在项目的 public/ 目录中添加 CNAME 文件

创建一个名为 CNAME 的文件（没有扩展名），放在 public/ 目录下，内容仅包含你要绑定的域名，例如：blog.geyuxu.com

⚠️ 注意：

• 不要添加 http:// 或 https://
• 文件中不要有空行或空格

---

✅ 3. 配置域名 DNS（在你的域名服务商后台）

登录你的域名服务商（如 Cloudflare、阿里云、Namecheap 等），添加以下 DNS 记录：

• 类型：CNAME
• 主机记录：blog（或你自定义的子域名）
• 指向：yourname.github.io（替换为你的 GitHub 用户名）
• TTL：默认或自动

示例：

类型	主机记录	值（指向）
CNAME	blog	geyuxu.github.io

---

✅ 4. 测试并访问

等待几分钟（DNS 生效时间视服务商而定），然后访问：https://blog.geyuxu.com

你应该可以看到部署成功的博客页面。

---

🎯 小贴士

• 每次部署时，gh-pages 会自动携带 public/CNAME 文件，无需手动设置。
• 如果你绑定的是顶级域名（如 geyuxu.com），可能还需添加 A 记录，指向 GitHub Pages 的 IP，详见 GitHub 官方文档。

---