部署到 Vercel

Vercel 是一个现代化的前端部署平台，为 Astro 项目提供开箱即用的支持。部署 ShokaX 主题到 Vercel 非常简单，只需几分钟即可完成。

前置要求

在开始之前，请确保：

✅ 已在 GitHub 上创建仓库并推送代码
✅ 拥有 Vercel 账号（可使用 GitHub 账号快速注册）
✅ 项目中已包含 vercel.json 配置文件（主题已内置）

快速部署

步骤 1：导入项目

登录 Vercel Dashboard
点击 “Add New…” → “Project”
选择 “Import Git Repository”

TODO: 添加 Vercel Dashboard 导入项目界面截图

步骤 2：连接 GitHub 仓库

在仓库列表中找到你的 ShokaX 项目
点击 “Import” 按钮
如果是首次导入，需要授权 Vercel 访问 GitHub

TODO: 添加选择 GitHub 仓库界面截图

步骤 3：配置项目

Vercel 会自动检测 Astro 框架并读取 vercel.json 配置，通常无需手动调整。

默认配置：

Framework Preset: Astro
Build Command: bun run build
Output Directory: dist
Install Command: bun install

TODO: 添加项目配置界面截图

步骤 4：部署

检查配置无误后，点击 “Deploy” 按钮
Vercel 会自动开始构建和部署
等待 1-3 分钟，构建完成后会显示部署成功页面

TODO: 添加部署进度界面截图

🎉 恭喜！ 你的 ShokaX 站点已成功部署，访问 Vercel 提供的 URL 即可查看。

配置说明

vercel.json 文件

项目根目录的 vercel.json 文件定义了 Vercel 部署配置：

{
  "framework": "astro",
  "installCommand": "bun install",
  "buildCommand": "bun run build",
  "outputDirectory": "dist",
  "headers": [
    {
      "source": "/_astro/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    },
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Content-Security-Policy",
          "value": "frame-ancestors 'none';"
        },
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        }
      ]
    }
  ]
}

配置说明：

字段	值	说明
`framework`	`astro`	指定框架类型
`installCommand`	`bun install`	依赖安装命令
`buildCommand`	`bun run build`	构建命令（包含 Pagefind 索引生成）
`outputDirectory`	`dist`	构建输出目录
`headers`	数组	HTTP 响应头配置

HTTP 头配置：

静态资源缓存（/_astro/*）
- Cache-Control: public, max-age=31536000, immutable
- 含义：静态资源缓存 1 年，不可变
- 好处：大幅提升访问速度，减少带宽消耗
安全策略（所有页面）
- Content-Security-Policy: frame-ancestors 'none'：禁止被嵌入 iframe
- X-Frame-Options: DENY：防止点击劫持攻击

astro.config.mjs 配置

确保 astro.config.mjs 中的 site 字段配置正确：

export default defineConfig({
  site: "https://yourdomain.com",  // 改为你的域名
  // ...其他配置
});

自动部署

Vercel 默认启用了 Git 集成，这意味着：

✅ 推送到 main/master 分支 → 自动触发生产环境部署
✅ 推送到其他分支 → 自动创建预览部署（Preview Deployment）
✅ 创建 Pull Request → 自动为 PR 创建预览链接

工作流程：

# 本地修改内容
echo "新文章内容" > src/posts/new-post.md

# 提交并推送
git add .
git commit -m "添加新文章"
git push origin main

# Vercel 自动触发部署（1-3 分钟后生效）

自定义域名

添加域名

进入项目的 Settings → Domains
输入你的域名（如 blog.example.com）
点击 “Add”

TODO: 添加自定义域名设置界面截图

配置 DNS

Vercel 会提供 DNS 配置指引，通常有两种方式：

方式 1：CNAME 记录（推荐）

在你的域名服务商处添加 CNAME 记录：

类型	名称	值
CNAME	`blog`	`cname.vercel-dns.com`

方式 2：A 记录

类型	名称	值
A	`@`	`76.76.21.21`

TODO: 添加 DNS 配置示例截图

配置 HTTPS

Vercel 自动为所有域名提供免费的 SSL 证书（Let’s Encrypt），无需额外配置。

添加域名后，Vercel 会自动：

验证域名所有权
申请 SSL 证书
强制 HTTPS 重定向

环境变量

添加环境变量

如果你的站点需要环境变量（如 API 密钥），可以在 Vercel 中配置：

进入项目的 Settings → Environment Variables
添加变量名和值
选择应用环境（Production / Preview / Development）
点击 “Save”

TODO: 添加环境变量配置界面截图

示例：

SITE_URL=https://yourdomain.com
GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

在代码中使用

export default defineConfig({
  site: import.meta.env.SITE_URL || "https://yourdomain.com",
});

性能优化

1. 启用 Edge Network

Vercel 的 Edge Network 默认启用，你的站点会自动分发到全球 CDN 节点。

好处：

🚀 更快的访问速度（就近访问）
🌍 全球可用性
💰 免费的 CDN 流量

2. 构建缓存

Vercel 会自动缓存 node_modules 和构建产物，加快后续部署速度。

首次部署：约 3-5 分钟
后续部署：约 1-2 分钟

3. 图片优化

如果使用 Astro 的 <Image /> 组件，Vercel 会自动优化图片：

WebP/AVIF 格式转换
响应式尺寸生成
懒加载

4. 预渲染优化

ShokaX 使用静态生成（SSG），Vercel 会直接提供 HTML 文件，速度极快。

监控与分析

查看部署日志

进入项目 Dashboard
点击任意部署记录
查看 “Building” 和 “Function Logs” 标签

TODO: 添加部署日志界面截图

Analytics（分析）

Vercel 提供内置的访问分析功能：

进入项目的 Analytics 标签
查看访问量、页面浏览、地域分布等数据

常见问题

Q: 构建失败，提示 “Bun not found”？

原因：Vercel 可能使用了 Node.js 而不是 Bun。

解决方案：

确保 vercel.json 中配置了正确的安装命令：

{
  "installCommand": "bun install",
  "buildCommand": "bun run build"
}

Q: 搜索功能不可用？

原因：构建命令未包含 Pagefind 索引生成。

解决方案：

确认 package.json 中的 build 脚本包含索引生成：

{
  "scripts": {
    "build": "bun run build:site && bun run build:index"
  }
}

Q: 部署成功但页面样式丢失？

原因：站点 URL 配置错误或静态资源路径问题。

解决方案：

检查 astro.config.mjs 中的 site 配置
确保使用 HTTPS 而不是 HTTP
清除浏览器缓存并刷新

Q: 如何回滚到之前的版本？

进入项目 Dashboard
在 Deployments 列表中找到之前的部署
点击 ”⋯” → “Promote to Production”

TODO: 添加回滚操作界面截图

Q: 构建时间过长（超过 5 分钟）？

可能原因：

文章数量太多（> 500 篇）
字体文件过大（未开启子集化）
依赖安装缓慢

优化建议：

启用字体子集化（参考字体配置文档）
检查是否有不必要的大文件
使用 Vercel 的 Turbo 模式（付费功能）

Q: 如何删除项目？

进入项目的 Settings → General
滚动到底部，找到 “Delete Project”
输入项目名称确认删除

替代方案

如果 Vercel 不适合你，可以考虑其他部署平台：

Netlify：功能类似 Vercel，免费版限制更宽松
Cloudflare Pages：免费且无限带宽
GitHub Pages：完全免费，需手动配置 GitHub Actions

部署到 Vercel

前置要求

快速部署

步骤 1：导入项目

步骤 2：连接 GitHub 仓库

步骤 3：配置项目

步骤 4：部署

配置说明

vercel.json 文件

astro.config.mjs 配置

自动部署

自定义域名

添加域名

配置 DNS

配置 HTTPS

环境变量

添加环境变量

在代码中使用

性能优化

1. 启用 Edge Network

2. 构建缓存

3. 图片优化

4. 预渲染优化

监控与分析

查看部署日志

Analytics（分析）

常见问题

Q: 构建失败，提示 “Bun not found”？

Q: 搜索功能不可用？

Q: 部署成功但页面样式丢失？

Q: 如何回滚到之前的版本？

Q: 构建时间过长（超过 5 分钟）？

Q: 如何删除项目？

替代方案

相关资源