同步博客到 Vercel
为什么要同步到vercel？主要是vercel 其实有国内cdn，如果绑上自己的域名，可以在国内直接访问，github pages不太行。
1. GitHub 仓库同步
同步流程很简单：将代码 push 到 GitHub，Vercel 在检测到仓库更新后会自动拉取并触发部署。
- 推送代码到 GitHub：使用
git push将本地变更推送到远端仓库。 - Vercel 自动监听：在项目关联后，Vercel 会对指定分支的 push 触发构建与部署。
提示
在 Vercel 控制台使用 “Import Git Repository” 并授权 GitHub，可以快速完成仓库关联与初始部署配置。2. Vercel 编译流程
Vercel 的构建与部署由两个关键文件驱动：项目配置 vercel.json 和构建脚本 vercel-build.sh。
| 文件 | 作用 |
| vercel.json | 项目配置（构建命令、输出目录、缓存策略） |
| vercel-build.sh | 构建脚本（下载编译器、执行构建） |
2.1 vercel.json 配置
代码 1 vercel.json 核心配置
{
"buildCommand": "bash vercel-build.sh",
"outputDirectory": "_site",
"headers": [
{
"source": "/(.*)",
"headers": [
{ "key": "Cache-Control", "value": "public, max-age=0, must-revalidate" }
]
},
{
"source": "/assets/(.*\\.(?:woff2|woff|ttf|otf|eot))",
"headers": [
{ "key": "Cache-Control", "value": "public, max-age=2592000, immutable" }
]
}
]
}关键配置说明：
buildCommand：指定构建命令，通常调用vercel-build.sh执行构建流程。outputDirectory：构建产物输出目录，本项目使用_site作为站点根目录。headers：按路径设置缓存策略：- HTML 页面：
max-age=0（不缓存），确保用户获取最新内容。 - 字体文件：
max-age=2592000（30 天）并设置immutable，减少重复下载。 - 资源文件（CSS/JS/图片）：根据需要灵活设置缓存时长。
- HTML 页面：
vercel-build.sh（构建脚本）
代码 2 vercel-build.sh 构建脚本
#!/bin/bash
# 安装 typst 编译器到项目目录
curl -fsSL https://github.com/typst/typst/releases/download/v0.14.2/typst-x86_64-unknown-linux-musl.tar.xz | tar -xJ
mv typst-x86_64-unknown-linux-musl/typst ./typst
rm -rf typst-x86_64-unknown-linux-musl
chmod +x typst
# 执行构建（项目使用 uv 脚本管理）
uv run build.py build构建脚本流程概览：
- 下载并解压 Typst 二进制到项目目录，设置可执行权限。
- 使用
uv run build.py build调用项目的构建脚本完成站点生成。
2.2 build.py 构建脚本
build.py 是站点构建的核心，负责：解析依赖、增量编译、处理资源并输出 _site。
代码 3 build.py 核心配置
#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.10"
# dependencies = [
# "pillow>=10.0.0",
# ]
# ///
CONTENT_DIR = Path("content") # 源文件目录
SITE_DIR = Path("_site") # 输出目录
ASSETS_DIR = Path("assets") # 静态资源目录
CONFIG_FILE = Path("config.typ") # 全局配置文件增量编译机制
build.py 实现增量编译以加速构建：
- 解析
#import/#include追踪文件依赖关系。 - 比较源文件与目标文件的修改时间，仅在必要时重新编译。
- 监测全局配置（如
config.typ）或同目录资源（图片、.bib、.md）的变化。
以下任一条件会触发重新编译：目标文件不存在、源文件或任一依赖文件较新、或资源文件发生变化。
构建产物结构（示意）
content/ 源文件目录
├── Blog/
│ └── index.typ 博客首页
├── Docs/
│ └── 同步vercel/
│ └── index.typ 本页面
└── ...
↓ typst compile
_site/ 输出目录
├── Blog/
│ └── index.html 生成的 HTML
├── Docs/
│ └── 同步vercel/
│ └── index.html 生成的 HTML
├── assets/ 静态资源
└── ...完整部署流程（示意）
代码 4 完整部署流程
┌─────────────────┐
│ 本地编写内容 │
│ (.typ 文件) │
└────────┬────────┘
│ git push
▼
┌─────────────────┐
│ GitHub 仓库 │
└────────┬────────┘
│ Webhook 触发
▼
┌─────────────────┐
│ Vercel │
│ ┌───────────┐ │
│ │ 拉取代码 │ │
│ └─────┬─────┘ │
│ ▼ │
│ ┌───────────┐ │
│ │ 下载 typst│ │
│ └─────┬─────┘ │
│ ▼ │
│ ┌───────────┐ │
│ │ 执行构建 │ │
│ │ build.py │ │
│ └─────┬─────┘ │
│ ▼ │
│ ┌───────────┐ │
│ │ 部署 _site│ │
│ └───────────┘ │
└─────────────────┘
│
▼
┌─────────────────┐
│ 用户访问 │
│ your-domain.com │
└─────────────────┘本页最后更新：2025-12-23