OpenInfoHub
Go back

在 Vercel 部署和维护 AstroPaper 博客完整指南

本教程将指导你在 Vercel 平台部署 AstroPaper 博客，并介绍如何进行日常维护和更新。内容基于 Vercel 官方文档、Astro 官方文档 和 AstroPaper 项目 整理。

Table of contents

Open Table of contents

什么是 Vercel 和 AstroPaper

Vercel 简介

Vercel 是一个现代化的云平台，专为前端开发者设计，提供：

AstroPaper 简介

AstroPaper 是一个基于 Astro 框架的博客主题，特点包括：

为什么选择 Vercel 部署 AstroPaper

前置准备

必需条件

  1. GitHub、GitLab 或 Bitbucket 账号
  2. Vercel 账号（可使用 GitHub 账号登录）
  3. 本地已安装 Node.js（推荐 v18.14.1 或更高版本）
  4. 本地已安装 Git

可选工具

第一步：创建 AstroPaper 项目

方法一：使用模板创建新项目

如果你还没有 AstroPaper 项目，可以使用以下命令创建：

# 使用 pnpm（推荐）
pnpm create astro@latest --template satnaing/astro-paper

# 使用 npm
npm create astro@latest -- --template satnaing/astro-paper

# 使用 yarn
yarn create astro --template satnaing/astro-paper

按照提示完成项目创建：

# 输入项目名称
Where should we create your new project?
./my-astro-blog

# 选择安装依赖
Install dependencies? (recommended)
Yes

# 选择初始化 Git 仓库
Initialize a new git repository? (optional)
Yes

方法二：Fork 现有项目

  1. 访问 AstroPaper GitHub 仓库
  2. 点击右上角的 “Fork” 按钮
  3. 克隆你 fork 的仓库到本地：
git clone https://github.com/your-username/astro-paper.git
cd astro-paper
pnpm install

本地测试

在部署前，先在本地测试项目：

# 启动开发服务器
pnpm run dev

# 访问 http://localhost:4321

确认项目正常运行后，进行构建测试：

# 构建项目
pnpm run build

# 预览构建结果
pnpm run preview

第二步：配置项目

基础配置

编辑 src/config.ts 文件，配置你的博客信息：

import type { Site, SocialObjects } from "./types";

export const SITE: Site = {
  website: "https://your-blog.vercel.app/", // 替换为你的域名
  author: "Your Name",
  profile: "https://your-profile-url.com/",
  desc: "你的博客描述",
  title: "你的博客标题",
  ogImage: "astropaper-og.jpg",
  lightAndDarkMode: true,
  postPerIndex: 4,
  postPerPage: 3,
  scheduledPostMargin: 15 * 60 * 1000, // 15 分钟
  showArchives: true,
  editPost: {
    url: "https://github.com/your-username/your-repo/edit/main/src/data/blog",
    text: "建议修改",
    appendFilePath: true,
  },
};

export const LOCALE = {
  lang: "zh-CN", // 设置语言
  langTag: ["zh-CN"],
} as const;

export const SOCIALS: SocialObjects = [
  {
    name: "Github",
    href: "https://github.com/your-username",
    linkTitle: `在 GitHub 上关注我`,
    active: true,
  },
  {
    name: "Mail",
    href: "mailto:your-email@example.com",
    linkTitle: `发送邮件给我`,
    active: true,
  },
  // 添加更多社交链接...
];

环境变量配置（可选）

如果需要使用 Google Site Verification，创建 .env 文件：

PUBLIC_GOOGLE_SITE_VERIFICATION=your-google-site-verification-value

注意：不要将 .env 文件提交到 Git 仓库。确保 .gitignore 中包含 .env。

Vercel 特定配置（可选）

对于静态部署，AstroPaper 不需要额外配置。但如果你想使用 Vercel 的高级功能（如 Web Analytics、Image Optimization），可以添加 Vercel 适配器。

安装 Vercel 适配器

# 使用 astro add 命令（推荐）
pnpm astro add vercel

# 或手动安装
pnpm install @astrojs/vercel

配置 astro.config.ts

如果使用 Vercel 适配器，编辑 astro.config.ts：

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/static";

export default defineConfig({
  site: "https://your-blog.vercel.app",
  integrations: [
    // 其他集成...
  ],
  output: "static", // 静态站点
  adapter: vercel({
    webAnalytics: {
      enabled: true, // 启用 Web Analytics
    },
    imageService: true, // 启用图片优化
  }),
});

注意：对于纯静态部署，不需要添加适配器。只有在使用 Vercel 特定功能时才需要。

第三步：推送代码到 Git 仓库

初始化 Git 仓库（如果还没有）

git init
git add .
git commit -m "Initial commit: AstroPaper blog"

创建 GitHub 仓库

  1. 访问 GitHub
  2. 点击右上角的 ”+” 按钮，选择 “New repository”
  3. 输入仓库名称（如 my-blog）
  4. 选择 Public 或 Private
  5. 不要初始化 README、.gitignore 或 license（本地已有）
  6. 点击 “Create repository”

推送代码到 GitHub

# 添加远程仓库
git remote add origin https://github.com/your-username/my-blog.git

# 推送代码
git branch -M main
git push -u origin main

第四步：在 Vercel 部署项目

方法一：通过 Vercel 网站部署（推荐）

1. 登录 Vercel

访问 Vercel 并登录（可使用 GitHub 账号）。

2. 导入项目

3. 配置项目

Vercel 会自动检测 Astro 项目并配置正确的设置：

如果需要，可以添加环境变量：

4. 部署

5. 访问你的博客

点击项目 URL 或 “Visit” 按钮，查看你的博客。

方法二：使用 Vercel CLI 部署

1. 安装 Vercel CLI

# 全局安装
pnpm install -g vercel

# 或使用 npm
npm install -g vercel

2. 登录 Vercel

vercel login

按照提示完成登录。

3. 部署项目

在项目根目录运行：

vercel

首次部署时，CLI 会询问一些问题：

? Set up and deploy "~/my-blog"? [Y/n] y
? Which scope do you want to deploy to? Your Name
? Link to existing project? [y/N] n
? What's your project's name? my-blog
? In which directory is your code located? ./
? Want to override the settings? [y/N] n

Vercel 会自动检测 Astro 并配置正确的设置。

4. 查看部署结果

部署完成后，CLI 会显示：

✅  Production: https://my-blog-xxx.vercel.app [copied to clipboard]

5. 部署到生产环境

# 部署到生产环境
vercel --prod

第五步：配置自定义域名（可选）

1. 在 Vercel 添加域名

2. 配置 DNS

Vercel 会提供 DNS 配置说明：

使用 A 记录（根域名）

Type: A
Name: @
Value: 76.76.21.21

使用 CNAME 记录（子域名）

Type: CNAME
Name: blog
Value: cname.vercel-dns.com

3. 等待 DNS 生效

DNS 配置通常需要几分钟到 48 小时生效。Vercel 会自动配置 SSL 证书。

4. 更新配置文件

在 src/config.ts 中更新网站 URL：

export const SITE: Site = {
  website: "https://blog.example.com/",
  // ...
};

在 astro.config.ts 中更新 site：

export default defineConfig({
  site: "https://blog.example.com",
  // ...
});

提交并推送更改：

git add .
git commit -m "Update site URL to custom domain"
git push

第六步：理解 Vercel 的部署流程

项目和部署的概念

部署类型

生产部署（Production Deployment）

预览部署（Preview Deployment）

自动部署流程

  1. 你推送代码到 Git 仓库
  2. Vercel 检测到推送事件
  3. 自动触发构建流程：
    • 克隆代码
    • 安装依赖
    • 运行构建命令
    • 优化资源
  4. 部署到全球 CDN
  5. 生成部署 URL
  6. 发送部署通知（如果配置了）

构建日志

在 Vercel 项目页面可以查看详细的构建日志：

第七步：日常维护和更新

添加新博客文章

1. 创建文章文件

在 src/data/blog/ 目录下创建新的 Markdown 文件：

# 按分类组织文章
src/data/blog/
├── ai/
│   └── my-new-ai-post.md
├── tools/
│   └── my-new-tool-post.md
└── _general/
    └── my-general-post.md

2. 编写文章内容

---
author: Your Name
pubDatetime: 2026-03-01T10:00:00+08:00
title: 我的新博客文章
slug: my-new-blog-post
featured: false
draft: false
tags:
  - 标签1
  - 标签2
description: 文章简短描述
---

文章内容开始...

## 标题

正文内容...

3. 本地预览

pnpm run dev

访问 http://localhost:4321 查看新文章。

4. 提交并推送

git add src/data/blog/
git commit -m "Add new blog post: my-new-blog-post"
git push

Vercel 会自动检测推送并部署更新。

更新现有文章

1. 编辑文章文件

直接编辑 src/data/blog/ 中的 Markdown 文件。

2. 本地测试

pnpm run dev

3. 提交更改

git add src/data/blog/
git commit -m "Update blog post: article-title"
git push

修改博客配置

更新站点信息

编辑 src/config.ts：

export const SITE: Site = {
  // 更新配置...
};

更新样式

编辑 src/styles/global.css 或 src/styles/typography.css。

添加新页面

在 src/pages/ 目录下创建新的 .astro 或 .md 文件。

升级依赖

定期更新项目依赖以获取最新功能和安全修复：

# 检查过时的包
pnpm outdated

# 更新所有依赖到最新版本
pnpm update

# 或更新特定包
pnpm update astro

# 测试更新后的项目
pnpm run build
pnpm run preview

# 提交更新
git add package.json pnpm-lock.yaml
git commit -m "Update dependencies"
git push

使用分支进行测试

在进行重大更改前，建议使用分支：

# 创建新分支
git checkout -b feature/new-design

# 进行更改并提交
git add .
git commit -m "Implement new design"

# 推送分支
git push -u origin feature/new-design

Vercel 会自动为这个分支创建预览部署，你可以在不影响生产环境的情况下测试更改。

创建 Pull Request

  1. 在 GitHub 上创建 Pull Request
  2. Vercel 会在 PR 中添加预览链接
  3. 审查更改
  4. 合并到 main 分支
  5. Vercel 自动部署到生产环境

回滚部署

如果新部署出现问题，可以快速回滚：

通过 Vercel 网站

  1. 进入项目页面
  2. 点击 “Deployments” 标签
  3. 找到之前的稳定部署
  4. 点击三个点菜单
  5. 选择 “Promote to Production”

通过 Git

# 回退到上一个提交
git revert HEAD

# 或回退到特定提交
git revert <commit-hash>

# 推送回退
git push

性能优化

启用 Vercel Analytics

1. 安装依赖

pnpm install @vercel/analytics

2. 添加到项目

编辑 src/layouts/Layout.astro：

---
import { inject } from '@vercel/analytics';

inject();
---

或在 astro.config.ts 中配置：

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/static";

export default defineConfig({
  adapter: vercel({
    webAnalytics: {
      enabled: true,
    },
  }),
});

3. 查看分析数据

在 Vercel 项目页面的 “Analytics” 标签查看访问数据。

启用 Speed Insights

Speed Insights 提供性能指标监控：

1. 安装依赖

pnpm install @vercel/speed-insights

2. 添加到项目

编辑 src/layouts/Layout.astro：

---
import { injectSpeedInsights } from '@vercel/speed-insights';

injectSpeedInsights();
---

3. 查看性能数据

在 Vercel 项目页面的 “Speed Insights” 标签查看性能指标。

图片优化

AstroPaper 使用 Astro 的 Image 组件，Vercel 会自动优化图片：

---
import { Image } from 'astro:assets';
import myImage from '../assets/my-image.png';
---

<Image src={myImage} alt="描述" />

缓存配置

Vercel 自动缓存静态资源。如需自定义缓存行为，创建 vercel.json：

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

高级配置

环境变量管理

在 Vercel 添加环境变量

  1. 进入项目 Settings
  2. 点击 “Environment Variables”
  3. 添加变量：
    • Name: PUBLIC_GOOGLE_SITE_VERIFICATION
    • Value: your-verification-code
    • Environment: Production, Preview, Development

在代码中使用

const verification = import.meta.env.PUBLIC_GOOGLE_SITE_VERIFICATION;

配置构建设置

在 Vercel 项目 Settings 的 “Build & Development Settings” 中可以自定义：

配置重定向

在 vercel.json 中配置重定向：

{
  "redirects": [
    {
      "source": "/old-blog/:slug",
      "destination": "/posts/:slug",
      "permanent": true
    }
  ]
}

配置 Git 集成

自动部署分支

在 Settings > Git 中配置：

忽略构建

如果某些提交不需要触发部署，在提交信息中添加 [skip ci]：

git commit -m "Update README [skip ci]"

监控和调试

查看部署日志

  1. 进入项目页面
  2. 点击具体的部署
  3. 查看 “Building” 和 “Functions” 日志

常见构建错误

依赖安装失败

# 确保 package.json 和 lock 文件同步
pnpm install
git add package.json pnpm-lock.yaml
git commit -m "Update dependencies"
git push

构建超时

如果构建时间过长，检查：

环境变量未定义

确保在 Vercel 项目设置中添加了所需的环境变量。

性能监控

使用 Vercel Analytics 和 Speed Insights 监控：

安全最佳实践

保护敏感信息

依赖安全

# 检查安全漏洞
pnpm audit

# 自动修复
pnpm audit --fix

HTTPS

Vercel 自动为所有部署提供 HTTPS，无需额外配置。

成本和限制

免费套餐

Vercel 免费套餐包括：

升级选项

如果需要更多资源，可以升级到 Pro 或 Enterprise 套餐。

故障排除

部署失败

检查构建日志

查看详细的错误信息，通常会指出问题所在。

本地复现

# 清理缓存
rm -rf node_modules .astro dist
pnpm install
pnpm run build

404 错误

确保 astro.config.ts 中的 site 配置正确：

export default defineConfig({
  site: "https://your-domain.com",
});

样式未加载

检查 public/ 目录中的静态资源是否正确引用。

图片显示问题

确保图片路径正确，使用 Astro 的 Image 组件：

import { Image } from 'astro:assets';

最佳实践总结

开发流程

  1. 在本地开发和测试
  2. 使用分支进行实验性更改
  3. 创建 Pull Request 进行代码审查
  4. 利用预览部署测试更改
  5. 合并到主分支自动部署到生产环境

内容管理

  1. 使用清晰的文件命名和目录结构
  2. 为文章添加完整的 frontmatter
  3. 定期备份内容
  4. 使用 Git 历史追踪更改

性能优化

  1. 优化图片大小和格式
  2. 启用 Vercel Analytics 监控性能
  3. 定期更新依赖
  4. 使用 Lighthouse 检查性能指标

安全维护

  1. 定期运行 pnpm audit
  2. 及时更新依赖
  3. 使用环境变量管理敏感信息
  4. 启用 Vercel 的安全功能

总结

通过本教程，你已经学会了：

Vercel 和 AstroPaper 的组合为你提供了一个强大、快速且易于维护的博客平台。利用 Vercel 的自动部署和全球 CDN，你可以专注于创作内容，而不用担心基础设施问题。

参考资源

内容基于 Vercel 和 Astro 官方文档改编，遵循相应的开源协议。

Share this post on:
Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email
Next Post
工作中常用的 Git 工作流完整指南