技术博客 · 2026/05/09

我是如何用 GitHub Pages 搭建个人简历博客的

记录一次从技术选型、工程搭建到 GitHub Pages 自动部署的个人网站实践。

GitHub PagesAstroGitHub Actions个人网站

这篇文章记录我从 0 到 1 搭建个人简历博客的过程。它不是单纯的工具教程，而是一次把“求职展示、项目沉淀、自动部署”串成闭环的工程实践复盘。

为什么要搭建这个网站

最初搭建这个网站的原因很简单：我希望有一个比 PDF 简历更长期、更灵活的展示入口。

PDF 简历适合投递，但它的空间有限，很难完整展示一个项目背后的设计过程、调试过程和复盘思考。GitHub 仓库可以展示代码，但如果没有上下文，别人很难快速理解项目解决了什么问题、我在其中承担了什么职责、遇到问题时又是如何定位和解决的。

所以我决定搭建一个个人简历博客网站，把在线简历、项目作品集和技术博客放在同一个入口中。这样一来，简历负责快速概览，项目页负责展示实践经历，博客则用于沉淀学习笔记、项目复盘和踩坑记录。

对我来说，这个网站不是一个单纯的展示页，而是一个持续更新的个人技术记录入口。

快速概览

模块当前状态后续重点
网站定位个人简历 + 项目作品集 + 技术博客用真实项目和复盘文章持续完善可信度
技术方案GitHub Pages + Astro + Markdown保持轻量，不急着引入复杂后台
部署方式GitHub Actions 自动构建发布每次推送前先本地构建验证
内容维护修改 Markdown 和 Astro 页面建立稳定的文章模板和项目展示结构

技术选型：为什么选择 GitHub Pages + Astro

第一版网站的目标不是做复杂功能，而是先完成“可访问、可展示、可持续维护”的最小闭环。因此技术选型上我优先考虑简单、稳定和低维护成本。

我最终选择了下面这套组合：

技术作用选择原因
GitHub Pages静态网站托管免费、稳定，适合个人主页、博客和项目展示
Astro静态站点框架适合内容型网站，页面结构清晰，支持 Markdown
GitHub Actions自动构建部署推送代码后自动构建并发布，减少手动操作
Markdown博客内容格式适合技术记录，维护成本低

GitHub Pages 的定位很适合个人主页：它可以直接从 GitHub 仓库发布静态网站，也支持自定义域名和 HTTPS。Astro 则适合这种“简历主页 + 博客 + 作品集”的内容型网站，既可以写页面组件，也可以用 Markdown 管理博客文章。

这套方案的好处是：网站本身足够轻量，不需要服务器、数据库和后台管理系统；后续要更新文章时，只需要新增或修改 Markdown 文件，再推送到 GitHub 即可。

第一版网站做什么，不做什么

为了避免第一版范围失控，我先把网站目标收敛到最核心的展示闭环。

第一版包含这些页面：

  • 首页：展示个人定位、求职方向、核心板块和最新博客。
  • 简历页：承接 PDF 简历内容，后续同步真实经历。
  • 项目页：展示代表项目，突出背景、职责、难点、方案和结果。
  • 博客页：用 Markdown 记录学习笔记、项目复盘和工具链踩坑。
  • 关于页：补充个人介绍、联系方式和网站维护原则。
  • 404 页面：处理不存在的页面。

同时，第一版明确不做这些功能：

  • 不做登录系统。
  • 不做数据库。
  • 不做后台 CMS。
  • 不做评论系统。
  • 不做复杂动画。
  • 暂时不绑定自定义域名。

这样做的原因是，GitHub Pages 本质上更适合静态网站，而我的核心需求是求职展示和技术记录。与其一开始堆功能，不如先把内容结构、部署流程和后续维护方式跑通。

工程搭建过程

工程搭建时，我先使用 Astro minimal 模板作为基础，然后按网站结构逐步拆分页面和组件。

当前项目主要目录如下：

src/
  components/
    Header.astro
    Footer.astro
    ProjectCard.astro
  content/
    blog/
  layouts/
    BaseLayout.astro
    BlogPostLayout.astro
  pages/
    index.astro
    resume.astro
    projects.astro
    about.astro
    404.astro
    blog/
      index.astro
      [slug].astro
  styles/
    global.css

其中，BaseLayout.astro 负责页面的公共 HTML 结构、标题、描述、导航和页脚。Header.astro 和 Footer.astro 作为公共组件复用在所有页面中。项目展示抽成了 ProjectCard.astro，方便后续替换成真实项目内容。

博客内容放在 src/content/blog/ 目录下，通过 Astro Content Collections 管理。这样每一篇文章都是一个 Markdown 文件，只要 frontmatter 信息完整，就可以自动出现在博客列表中，并生成对应的详情页。

部署过程：从本地到 GitHub Pages

本地构建通过后，我将网站部署到 GitHub Pages。因为我的目标是个人主页，所以仓库名使用：

bearsio.github.io

最终访问地址是：

https://bearsio.github.io

Astro 配置中设置了网站地址：

export default defineConfig({
  site: 'https://bearsio.github.io',
});

由于这是个人主页根站点，不需要配置 base。如果是项目站点，例如 https://bearsio.github.io/resume-blog-site/，才需要额外配置 base: '/resume-blog-site/'。

部署部分使用 GitHub Actions。流程是：当代码推送到 main 分支后，Actions 自动安装依赖、构建 Astro 项目，并把构建产物发布到 GitHub Pages。

整体流程可以概括为：

本地修改代码
  -> npm run build 验证
  -> git commit
  -> git push
  -> GitHub Actions 自动构建
  -> GitHub Pages 发布

遇到的问题与解决方法

这次建站过程中遇到的几个问题，反而是最有价值的部分。它们让我更清楚地理解了本地环境、Astro 版本变化和 GitHub Pages 部署机制。

1. create-astro 模板拉取失败

现象：一开始创建 Astro 项目时，模板下载失败，请求被导向了本机代理地址。

错误信息类似：

Failed to fetch https://github.com/withastro/astro/tree/examples/minimal/
connect ECONNREFUSED 127.0.0.1:443

定位：从错误信息看，请求被导向了 127.0.0.1，说明当前环境存在代理配置，但本地代理没有正常响应。进一步检查后发现，npm registry 本身可用，问题主要出现在 create-astro 从 GitHub 拉取模板的阶段。

解决：临时清空代理环境变量后重新执行模板创建命令。重新拉取后，Astro minimal 模板成功创建。

收获：遇到网络类错误时，不能只看“下载失败”这个表象，还要看请求实际被导向了哪里。127.0.0.1、端口号、代理变量这些信息往往能直接指向根因。

2. Astro 6 Content Collections 配置变化

现象：在配置博客内容集合时，我一开始使用了旧版写法，把配置放在：

src/content/config.ts

构建时出现了这个错误：

LegacyContentConfigError
Found legacy content config file in src/content/config.ts

定位：错误提示说明，当前项目使用的是 Astro 6，而 Astro 6 已经移除了旧版 Content Collections 配置方式。新的写法需要使用：

src/content.config.ts

并通过 glob() loader 加载本地 Markdown 文件。

解决：调整后的思路是：

const blog = defineCollection({
  loader: glob({
    base: './src/content/blog',
    pattern: '**/*.{md,mdx}',
  }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

同时，博客详情页也需要使用 render(post) 来渲染 Markdown 内容。

收获：框架版本变化会直接影响项目约定。遇到构建错误时，应该优先看错误类型和迁移提示，而不是只修改表层代码。修正后，博客列表和详情页都能正常构建。

3. GitHub Pages 部署阶段 404

现象：第一次 GitHub Actions 部署时，构建阶段已经成功，但 deploy 阶段失败，错误信息是：

Failed to create deployment (status: 404)
Ensure GitHub Pages has been enabled

定位：这个问题不是 Astro 构建失败，而是 GitHub Pages 部署入口还没有正确启用。也就是说，Actions 已经生成了网站文件，但 GitHub Pages 当时还没有切换到 GitHub Actions 部署模式。

解决：在仓库中进入：

Settings -> Pages -> Build and deployment -> Source

将 Source 设置为：

GitHub Actions

然后重新运行失败的 workflow。重新运行后，build 和 deploy 两个 job 都成功通过，网站也可以正常访问。

收获：CI 构建成功不等于部署链路完全打通。排查部署问题时，要区分“项目构建错误”和“平台发布配置错误”。

当前网站效果

目前网站已经可以通过下面这个地址访问：

https://bearsio.github.io

第一版已经包含：

  • 首页
  • 在线简历页
  • 项目作品页
  • 博客列表页
  • 博客详情页
  • 关于页
  • 404 页面

现阶段内容仍以框架和占位内容为主，后续会逐步补充真实简历信息、代表项目、项目截图和更完整的技术文章。

总结

这次建站过程完整走了一遍从需求分析、技术选型、工程搭建、内容组织到自动部署的流程。

虽然网站本身是一个静态站，但其中涉及到项目结构设计、Astro 内容集合、GitHub Actions 自动部署、GitHub Pages 配置以及实际问题排查。对我来说，这不仅是一次建站实践，也是一次工程化流程的整理。

后续我会把这个网站作为个人简历和技术博客的统一入口，持续记录项目经验、学习过程和问题解决思路。