Astro + GitHub Pages + Vercel + 腾讯云域名 博客部署全指南

搭建个人博客的核心需求，无非是「简单易维护、免费部署、自定义域名」。本文整合 Astro 博客初始化、GitHub Pages 自动化部署、Vercel 平台部署、腾讯云域名绑定全流程，全程脱敏无个人信息，新手可直接照着操作，零技术门槛也能快速上线属于自己的个人博客。

一、前置准备

开始操作前，先准备好以下基础环境和工具，避免操作中卡顿：

二、Astro 博客项目初始化

Astro 是一款轻量、高性能的静态站点生成器，特别适合搭建博客，自带博客模板，无需从零开发。

1. 本地创建 Astro 博客项目

打开电脑终端（Windows 用 PowerShell/CMD，Mac/Linux 用终端），依次执行以下命令，一键初始化博客模板：

# 1. 创建 Astro 博客项目（my-astro-blog 可自定义项目名称）
pnpm create astro@latest my-astro-blog -- --template blog

# 2. 进入项目目录
cd my-astro-blog

# 3. 安装项目依赖
pnpm install

# 4. 本地预览（可选，启动后访问 http://localhost:4321 查看效果）
pnpm dev

执行完成后，本地就能看到 Astro 默认的博客模板，后续可按需修改主题、添加文章。

2. 关键配置：astro.config.mjs

这是 Astro 项目的核心配置文件，直接影响后续部署后的访问效果，重点配置「site」参数：

import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://你的自定义域名',
});

三、GitHub 仓库创建与代码推送

利用 GitHub Pages 免费部署博客，需要创建一个专属仓库，将本地 Astro 项目推送到 GitHub 远程仓库。

1. 创建 GitHub 仓库

登录 GitHub，点击右上角「New repository」，按以下配置创建仓库：

• Repository name：填写「用户名.github.io」
• Visibility：选择「Public」
• Add README/Add .gitignore/Add license：均选择「Off」

2. 本地代码关联并推送至 GitHub

# 1. 初始化 Git 仓库
git init

# 2. 将主分支重命名为 main
git branch -M main

# 3. 关联 GitHub 仓库
git remote add origin https://github.com/用户名/用户名.github.io.git

# 4. 提交所有代码
git add .
git commit -m "init: 初始化 Astro 博客项目"

# 5. 推送到 GitHub 远程仓库
git push -u origin main

四、GitHub Actions 自动化部署配置

配置 GitHub Actions 后，后续每次推送代码，都会自动触发构建和部署，无需手动操作。

1. 创建部署工作流文件

在 Astro 项目根目录，新建文件夹「.github/workflows」，然后在该文件夹下新建文件「deploy.yml」：

name: Deploy Astro Blog to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install

      - name: Build Astro site
        run: pnpm run build

      - name: Upload build artifacts
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

2. 提交并推送工作流文件

git add .github/workflows/deploy.yml
git commit -m "ci: 添加 GitHub Actions 自动化部署工作流"
git push origin main

推送完成后，进入 GitHub 仓库，点击顶部「Actions」，可看到正在执行的部署工作流。

五、Vercel 平台部署与配置

Vercel 是一个专注于前端项目的部署平台，提供免费的全球 CDN 加速、无缝集成 GitHub、自动配置 HTTPS，是托管 Astro 博客的理想选择。

1. GitHub 仓库关联 Vercel

1. 访问 Vercel 官网，点击右上角「Sign Up」或「Log In」
2. 选择「Continue with GitHub」，授权 Vercel 访问你的 GitHub 账号
3. 在 Vercel Dashboard 点击「Add New」→ 「Project」
4. 从列表中找到你的博客仓库（用户名.github.io），点击「Import」

2. Vercel 项目配置

在项目配置页面，进行以下设置：

• Framework Preset：Astro（Vercel 会自动识别）
• Root Directory：保持默认（/）
• Build Command：npm run build（若使用 pnpm 则为 pnpm run build）
• Output Directory：dist

2.1 创建 vercel.json 配置文件（重要）

在 Astro 项目根目录，新建文件 vercel.json，内容如下：

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "astro",
  "installCommand": "npm install --legacy-peer-deps",
  "devCommand": "npm run dev"
}

3. 部署与预览

1. 点击「Deploy」开始部署
2. 等待几分钟，Vercel 会自动构建并部署博客
3. 部署完成后，你会获得一个 项目名.vercel.app 的预览域名
4. 访问该域名，确认博客能正常显示

4. 配置自定义域名

1. 在 Vercel 项目 Dashboard，点击「Settings」→「Domains」
2. 在输入框中填写你的自定义域名（如 blog.xxx.com）
3. 点击「Add」添加域名
4. Vercel 会自动配置 DNS 记录（可在腾讯云 DNS 解析中查看新增的 CNAME 记录）
5. 等待几分钟，Vercel 会自动申请并配置 HTTPS 证书

5. 设置主域名（可选）

如果你有多个域名指向同一博客，可以在 Vercel 中设置主域名：

1. 在 Domains 页面，找到要设为主域名的域名
2. 点击右侧「…」→「Set as Primary」

六、腾讯云域名绑定 Vercel

部署成功后，我们将腾讯云的自定义域名绑定到 Vercel 平台，享受全球 CDN 加速访问。

1. 腾讯云 DNS 解析配置

登录腾讯云 DNS 解析 DNSPod 控制台，找到需要绑定的域名，点击「解析」进入解析记录页面。

方案 A：绑定根域名（如 xxx.com）

需要添加 CNAME 记录指向 Vercel：

方案 B：绑定二级域名（如 blog.xxx.com，推荐）

仅需添加 1 条 CNAME 记录：

2. Vercel 域名验证与 HTTPS 配置

1. 在 Vercel 项目 Dashboard，点击「Settings」→「Domains」
2. 在域名列表中可以看到已添加的域名
3. Vercel 会自动验证域名所有权，并申请 Let’s Encrypt 免费 HTTPS 证书
4. 证书签发后，域名状态会显示「Valid Certificate」
5. 点击域名右侧的编辑按钮，勾选「Force HTTPS」

七、生效验证与访问测试

1. 刷新本地 DNS（加速生效）

• Windows：执行 ipconfig /flushdns
• Mac/Linux：执行 sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

2. 访问测试

在浏览器中输入自定义域名，若能正常打开 Astro 博客，且地址栏有小锁图标（HTTPS 生效），说明所有配置都已成功。

八、常见问题排查

九、后续维护与优化

• 主题美化：修改 Astro 项目 src 目录下的组件和样式
• 文章写作：在 src/posts 目录下新建 .md 或 .mdx 文件
• 域名维护：按时在腾讯云续费域名
• 备份代码：定期备份 GitHub 仓库代码
• Vercel 更新：代码推送到 GitHub 后，Vercel 会自动重新部署

整个流程从 Astro 项目初始化、GitHub 仓库创建、自动化部署，到 Vercel 平台托管、腾讯云域名绑定，全程免费、可落地，新手也能快速上手。核心要点是：正确配置 astro.config.mjs、确保 GitHub Actions 权限完整、在 Vercel 正确配置构建命令、DNS 解析记录指向 Vercel，只要按步骤操作，就能顺利上线自己的个人博客。