Hexo 博客零成本部署到 Vercel 完整指南

详细记录如何将 Hexo 静态博客免费部署到 Vercel 平台的完整过程，包括自动化部署、自定义域名配置和常见问题解决方案。

为什么选择 Vercel

Vercel 的核心优势

在众多静态网站托管平台中，Vercel 脱颖而出的原因：

  • 🆓 完全免费：个人项目无任何费用，包含 CDN 和 SSL 证书
  • ⚡ 极速部署：全球 CDN 节点，访问速度极快
  • 🔄 自动化 CI/CD：Git 推送即自动构建部署
  • 🌐 域名友好：免费提供 .vercel.app 域名，支持自定义域名
  • 📱 移动优化：自动适配移动端，性能卓越
  • 🔧 零配置：支持多种框架，Hexo 开箱即用

对比其他平台

平台 免费额度 部署速度 CDN 自定义域名 推荐指数
Vercel 100GB 带宽/月 ⭐⭐⭐⭐⭐ 全球 免费 ⭐⭐⭐⭐⭐
Netlify 100GB 带宽/月 ⭐⭐⭐⭐ 全球 免费 ⭐⭐⭐⭐
GitHub Pages 1GB 存储 ⭐⭐⭐ 有限 免费 ⭐⭐⭐
Cloudflare Pages 无限 ⭐⭐⭐⭐ 全球 免费 ⭐⭐⭐⭐

部署前准备工作

环境要求检查

确保你的开发环境满足以下要求：

1
2
3
4
5
6
7
8
9
10
11
# 检查 Node.js 版本（建议 16.x 及以上）
node --version
# v18.17.0

# 检查 npm 版本
npm --version
# 9.6.7

# 检查 Git 版本
git --version
# git version 2.41.0

Hexo 项目结构确认

标准的 Hexo 项目应包含以下核心文件：

1
2
3
4
5
6
7
8
9
10
hexo-blog/
├── _config.yml          # 站点配置文件
├── _config.anzhiyu.yml  # 主题配置文件（如使用安知鱼主题）
├── package.json         # 依赖管理文件
├── source/             # 源文件目录
│   ├── _posts/         # 文章目录
│   └── ...
├── themes/             # 主题目录
├── scaffolds/          # 文章模板
└── public/             # 生成的静态文件（部署时忽略）

必要配置检查

1. package.json 配置优化

确保你的 package.json 包含正确的构建脚本：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "name": "hexo-blog",
  "version": "1.0.0",
  "scripts": {
    "build": "hexo clean && hexo generate",
    "clean": "hexo clean",
    "deploy": "hexo deploy",
    "server": "hexo server",
    "start": "hexo server"
  },
  "dependencies": {
    "hexo": "^7.0.0",
    "hexo-cli": "^4.3.0",
    "hexo-generator-archive": "^2.0.0",
    "hexo-generator-category": "^2.0.0",
    "hexo-generator-index": "^3.0.0",
    "hexo-generator-tag": "^2.0.0",
    "hexo-renderer-ejs": "^2.0.0",
    "hexo-renderer-marked": "^6.0.0",
    "hexo-renderer-stylus": "^3.0.0",
    "hexo-server": "^3.0.0",
    "hexo-theme-anzhiyu": "latest"
  }
}

2. _config.yml 站点配置

关键配置项检查：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 站点基本信息
title: 你的博客标题
subtitle: 副标题
description: 博客描述
keywords: 关键词
author: 你的名字
language: zh-CN
timezone: Asia/Shanghai

# 部署相关配置
url: https://yourdomain.vercel.app  # 将替换为你的域名
root: /
permalink: :year/:month/:day/:title/
permalink_defaults:
pretty_urls:
  trailing_index: true
  trailing_html: true

# 构建配置
skip_render:
  - "README.md"
  - "*.html"

详细部署步骤

第一步：代码托管到 GitHub

1. 创建 GitHub 仓库

1
2
3
4
5
6
# 在项目根目录初始化 Git
cd your-hexo-blog
git init

# 添加远程仓库（替换为你的仓库地址）
git remote add origin https://github.com/yourusername/hexo-blog.git

2. 配置 .gitignore 文件

创建 .gitignore 文件，避免提交不必要的文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Build output
public/
.deploy*/

# Environment files
.env
.env.local
.env.*.local

# IDE files
.vscode/
.idea/
*.swp
*.swo

# OS files
.DS_Store
Thumbs.db

# Hexo cache
db.json
*.log

# Theme specific (如果主题作为子模块)
themes/*/node_modules/

3. 首次提交代码

1
2
3
4
5
6
7
8
# 添加所有文件
git add .

# 提交代码
git commit -m "Initial commit: Add Hexo blog"

# 推送到 GitHub
git push -u origin main

第二步：在 Vercel 创建项目

1. 注册登录 Vercel

访问 vercel.com 并使用 GitHub 账号登录：

  1. 点击 “Sign Up” 或 “Login”
  2. 选择 “Continue with GitHub”
  3. 授权 Vercel 访问你的 GitHub 账户

2. 导入 GitHub 项目

在 Vercel 控制台：

  1. 点击 “New Project”
  2. 选择 “Import Git Repository”
  3. 找到你的 Hexo 项目仓库
  4. 点击 “Import”

3. 配置构建设置

重要配置项：

1
2
3
4
5
6
7
8
9
10
11
12
13
# Framework Preset（框架预设）
Framework Preset: Other

# Build & Development Settings（构建和开发设置）
Build Command: npm run build
Output Directory: public
Install Command: npm install

# Root Directory（根目录）
Root Directory: ./（保持默认）

# Node.js Version（Node.js 版本）
Node.js Version: 18.x（推荐）

详细配置截图说明：

  1. Framework Preset: 选择 “Other” 而不是 “Hexo”（避免配置冲突）
  2. Build Command: 确保使用 npm run build 而不是默认命令
  3. Output Directory: 必须设置为 public（Hexo 生成目录）
  4. Install Command: 保持 npm install（或 yarn install）

第三步：环境变量配置

1. 必要环境变量

在 Vercel 项目设置中添加环境变量：

1
2
3
4
5
6
7
8
# 时区设置
TZ=Asia/Shanghai

# Node.js 环境
NODE_ENV=production

# 包管理器指定（可选）
NPM_CONFIG_PRODUCTION=false

2. 主题相关环境变量

如果使用了需要密钥的功能（如评论系统），添加相应环境变量：

1
2
3
4
5
6
7
8
# Algolia 搜索（如果启用）
ALGOLIA_APP_ID=your_app_id
ALGOLIA_API_KEY=your_api_key
ALGOLIA_INDEX_NAME=your_index_name

# 其他第三方服务密钥
# VALINE_APP_ID=xxx
# VALINE_APP_KEY=xxx

第四步：首次部署测试

1. 触发部署

配置完成后，Vercel 会自动开始首次部署：

1
2
3
4
5
6
# 部署状态可以在 Vercel 控制台查看
Building...
├── Installing dependencies
├── Running build command
├── Uploading build outputs
└── Deployment ready

2. 部署成功验证

部署成功的标志：

  • ✅ 构建日志无错误
  • ✅ 生成 public 目录
  • ✅ 分配临时域名（如 project-name-xxx.vercel.app）
  • ✅ 网站可正常访问

3. 常见首次部署问题

问题 1: 构建失败 - 依赖问题

1
2
3
4
5
6
7
8
# 错误信息示例
Error: Cannot find module 'hexo-renderer-xxx'

# 解决方案
npm install hexo-renderer-xxx --save
git add package.json package-lock.json
git commit -m "Add missing dependency"
git push

问题 2: 路径问题导致样式丢失

1
2
3
# _config.yml 中确保配置正确
url: https://your-project.vercel.app
root: /

问题 3: 主题文件丢失

1
2
3
4
5
# 如果主题是通过 git clone 安装的，需要处理 .git 目录
rm -rf themes/your-theme/.git
git add themes/
git commit -m "Add theme files"
git push

自定义域名配置

第一步：域名准备

1. 域名选择建议

推荐域名后缀：

  • .com - 最通用，SEO 友好
  • .cn - 国内访问速度好
  • .dev - 开发者专用，自带 HTTPS
  • .app - 现代感强，Google 官方后缀

2. 域名购买渠道

国外渠道（推荐）：

服务商 价格范围 特点 推荐指数
Namecheap $8-15/年 便宜稳定，隐私保护 ⭐⭐⭐⭐⭐
Cloudflare $8-12/年 成本价，DNS 免费 ⭐⭐⭐⭐⭐
Google Domains $12-15/年 谷歌出品，集成度高 ⭐⭐⭐⭐

国内渠道：

  • 阿里云：适合国内备案
  • 腾讯云：价格适中
  • 华为云：企业级服务

第二步：在 Vercel 中配置域名

1. 添加自定义域名

在 Vercel 项目设置中：

  1. 进入项目设置页面
  2. 点击 “Domains” 选项卡
  3. 输入你的域名（如 yourdomain.com）
  4. 点击 “Add”

2. 获取 DNS 配置信息

Vercel 会显示需要配置的 DNS 记录：

主域名配置：

1
2
3
Type: A
Name: @
Value: 76.76.19.61

www 子域名配置：

1
2
3
Type: CNAME
Name: www
Value: cname.vercel-dns.com

第三步：配置 DNS 解析

1. 在域名注册商处配置

以 Cloudflare 为例：

  1. 登录 Cloudflare 控制台
  2. 选择你的域名
  3. 进入 DNS 设置页面
  4. 添加以下记录：
1
2
3
4
5
6
7
8
9
10
11
# 主域名 A 记录
Type: A
Name: @
IPv4 address: 76.76.19.61
Proxy status: DNS only（灰色云朵）

# www 子域名 CNAME 记录
Type: CNAME
Name: www
Target: cname.vercel-dns.com
Proxy status: DNS only（灰色云朵）

2. DNS 验证和等待

配置完成后：

  • DNS 传播时间：通常 5-30 分钟
  • 全球生效时间：最多 48 小时
  • 验证命令：
1
2
3
4
5
6
7
8
# 检查 A 记录
nslookup yourdomain.com

# 检查 CNAME 记录
nslookup www.yourdomain.com

# 在线检查工具
# https://dnschecker.org/

第四步：SSL 证书自动配置

Vercel 会自动为你的域名申请和配置 SSL 证书：

  • 证书类型：Let’s Encrypt 免费证书
  • 自动续期：无需手动操作
  • 配置时间：域名验证通过后 5-10 分钟

验证 HTTPS 生效：

1
2
3
4
# 检查 SSL 证书
curl -I https://yourdomain.com

# 应该返回 200 状态码和正确的响应头

自动化部署配置

Git 工作流配置

1. 分支策略建议

推荐分支结构：

1
2
3
main (production)     # 生产环境，自动部署
├── develop          # 开发环境，预览部署
└── feature/*        # 功能分支，PR 预览

2. Vercel 分支部署配置

在 Vercel 项目设置中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Production Branch（生产分支）
Production Branch: main

# Automatic Preview Deployments（自动预览部署）
Git Integration: Enabled
Preview Deployments: All branches

# Build & Development Settings per Branch
main:
  Build Command: npm run build
  Output Directory: public
  
develop:
  Build Command: npm run build
  Output Directory: public

自动化工作流优化

1. 创建 GitHub Actions（可选增强）

在项目根目录创建 .github/workflows/deploy.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
name: Deploy to Vercel

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
      
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Build site
      run: npm run build
      
    - name: Deploy to Vercel
      uses: amondnet/vercel-action@v25
      with:
        vercel-token: ${{ secrets.VERCEL_TOKEN }}
        vercel-org-id: ${{ secrets.ORG_ID }}
        vercel-project-id: ${{ secrets.PROJECT_ID }}
        working-directory: ./

2. 配置构建缓存优化

在 vercel.json 中添加构建优化配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "version": 2,
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build",
      "config": {
        "distDir": "public"
      }
    }
  ],
  "routes": [
    {
      "src": "/(.*)",
      "dest": "/$1"
    }
  ],
  "functions": {
    "app.js": {
      "includeFiles": "public/**"
    }
  },
  "crons": []
}

性能优化配置

CDN 和缓存策略

1. Vercel 默认缓存优化

Vercel 自动提供：

  • 静态资源缓存：CSS、JS、图片自动缓存
  • 全球 CDN：就近访问，加速全球用户访问
  • 智能压缩：Gzip/Brotli 自动压缩
  • HTTP/2 支持：现代协议优化

2. 自定义缓存头配置

在 vercel.json 中配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        },
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "X-XSS-Protection",
          "value": "1; mode=block"
        }
      ]
    },
    {
      "source": "/static/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

构建性能优化

1. 依赖优化

1
2
3
4
5
6
7
8
9
10
{
  "scripts": {
    "build": "hexo clean && hexo generate",
    "build:fast": "hexo generate"
  },
  "engines": {
    "node": ">=16.0.0",
    "npm": ">=8.0.0"
  }
}

2. 图片优化建议

1
2
3
4
5
6
7
8
# _config.yml 中配置图片处理
post_asset_folder: true
marked:
  prependRoot: true
  postAsset: true

# 推荐使用 WebP 格式
# 可配合图床服务（如七牛云、阿里云OSS）

常见问题和解决方案

部署相关问题

问题 1: 构建超时

错误现象：

1
Error: Build timed out after 10m0s

解决方案：

  1. 优化构建脚本：
1
2
3
4
5
{
  "scripts": {
    "build": "hexo clean && hexo generate --silent"
  }
}
  1. 减少不必要的插件：
1
2
3
4
# _config.yml - 禁用开发时插件
plugins:
  - hexo-generator-sitemap  # 保留
  # - hexo-admin             # 移除开发插件
  1. 升级 Vercel 套餐（如需要）

问题 2: 静态资源 404

错误现象：

  • CSS/JS 文件 404
  • 图片无法加载
  • 字体文件丢失

解决方案：

  1. 检查 URL 配置：
1
2
3
# _config.yml
url: https://yourdomain.com  # 不要有尾斜杠
root: /
  1. 确认资源路径：
1
2
3
# 主题配置文件中
CDN:
  enable: false  # 避免 CDN 路径冲突
  1. 检查 .gitignore：
    确保静态资源文件被正确提交

问题 3: 主题样式异常

错误现象：

  • 页面布局错乱
  • 主题特色功能失效
  • 自定义样式不生效

解决方案：

  1. 主题文件完整性检查：
1
2
3
# 确保主题文件完整
ls -la themes/your-theme/
# 应包含 source、layout、_config.yml 等目录
  1. 依赖安装检查：
1
2
3
# 安装主题依赖
cd themes/your-theme
npm install  # 如果主题有 package.json
  1. 配置文件同步：
1
2
# 确保主题配置正确
theme: anzhiyu  # 主题名称

自定义域名问题

问题 1: 域名解析不生效

排查步骤：

  1. DNS 检查：
1
2
3
4
5
6
7
# 检查 A 记录
dig yourdomain.com A

# 检查 CNAME 记录
dig www.yourdomain.com CNAME

# 应该指向 Vercel 的 IP 或 CNAME

  1. DNS 传播检查：
    使用在线工具：https://dnschecker.org/

  2. Cloudflare 用户特别注意：

1
2
Proxy Status: DNS only (灰色云朵)
不要开启代理（橙色云朵）

问题 2: SSL 证书问题

错误现象：

1
2
NET::ERR_CERT_AUTHORITY_INVALID
Your connection is not private

解决方案：

  1. 等待证书生成：首次配置需 10-30 分钟
  2. 检查域名验证：确保 DNS 解析正确
  3. 强制刷新：清除浏览器缓存和 DNS 缓存
1
2
3
4
5
# 清除 DNS 缓存 (Windows)
ipconfig /flushdns

# 清除 DNS 缓存 (macOS)
sudo dscacheutil -flushcache

性能相关问题

问题 1: 加载速度慢

优化策略：

  1. 启用压缩：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// vercel.json
{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Content-Encoding",
          "value": "gzip"
        }
      ]
    }
  ]
}
  1. 图片优化：
  • 使用 WebP 格式
  • 配置图床 CDN
  • 启用懒加载
  1. 代码分割：
1
2
3
4
5
6
7
8
# 主题配置中启用代码分割
minify:
  html:
    enable: true
  css:
    enable: true
  js:
    enable: true

问题 2: 移动端适配问题

解决方案：

  1. 响应式设计检查：
1
2
<!-- 确保有 viewport meta 标签 -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
  1. 移动端优化配置：
1
2
3
4
# 主题配置
mobile:
  enable: true
  scale: 1.0

高级配置和扩展

多环境部署策略

1. 分支环境配置

1
2
3
4
5
6
7
8
9
10
11
12
13
# 生产环境 (main 分支)
Production:
  Domain: yourdomain.com
  Build Command: npm run build
  Environment Variables:
    NODE_ENV: production
    
# 预览环境 (develop 分支)  
Preview:
  Domain: preview-yourdomain.vercel.app
  Build Command: npm run build:preview
  Environment Variables:
    NODE_ENV: development

2. 环境变量管理

生产环境变量：

1
2
3
NODE_ENV=production
SITE_URL=https://yourdomain.com
ANALYTICS_ID=GA_MEASUREMENT_ID

开发环境变量：

1
2
3
NODE_ENV=development
SITE_URL=https://preview-yourdomain.vercel.app
DEBUG=true

集成第三方服务

1. 评论系统集成

Valine 配置示例：

1
2
3
4
5
6
# 主题配置文件
valine:
  enable: true
  appId: # Vercel 环境变量 VALINE_APP_ID
  appKey: # Vercel 环境变量 VALINE_APP_KEY
  placeholder: 欢迎留言讨论

Vercel 环境变量配置：

1
2
VALINE_APP_ID=your_leancloud_app_id
VALINE_APP_KEY=your_leancloud_app_key

2. 搜索功能集成

Algolia 搜索配置：

1
2
3
4
5
# _config.yml
algolia:
  applicationID: # 环境变量
  apiKey: # 环境变量
  indexName: # 环境变量

自动化索引更新：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# .github/workflows/algolia.yml
name: Update Algolia Index

on:
  push:
    branches: [ main ]

jobs:
  algolia:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Update search index
        run: |
          npm install
          npm run algolia
        env:
          ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
          ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}

监控和分析

1. 网站性能监控

Vercel Analytics 集成：

1
2
3
4
5
6
7
8
9
10
11
// 在模板中添加
import { Analytics } from '@vercel/analytics/react';

export default function App() {
  return (
    <>
      <Component {...pageProps} />
      <Analytics />
    </>
  );
}

2. SEO 优化配置

sitemap 自动生成：

1
2
3
4
5
6
7
# _config.yml
sitemap:
  path: sitemap.xml
  template: ./sitemap_template.xml
  rel: false
  tags: true
  categories: true

robots.txt 配置：

1
2
3
4
# source/robots.txt
User-agent: *
Allow: /
Sitemap: https://yourdomain.com/sitemap.xml

最佳实践总结

开发工作流建议

1. 本地开发环境

1
2
3
4
5
6
7
8
9
10
11
# 本地开发服务器
npm run server
# 访问 http://localhost:4000

# 本地构建测试
npm run build
# 检查 public 目录输出

# 预览构建结果
npx serve public
# 访问 http://localhost:3000

2. Git 提交规范

1
2
3
4
5
6
7
8
# 功能开发
git checkout -b feature/new-post
git add .
git commit -m "feat: add new blog post about Vercel deployment"
git push origin feature/new-post

# 提交 Pull Request 预览部署
# 合并到 main 分支触发生产部署

3. 代码质量保证

pre-commit 钩子配置：

1
2
3
4
5
6
7
8
9
10
11
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,css,md}": ["prettier --write", "git add"],
    "*.md": ["hexo clean && hexo generate", "git add public"]
  }
}

安全最佳实践

1. 敏感信息保护

1
2
3
4
5
6
# 永远不要在代码中硬编码敏感信息
# ❌ 错误做法
const apiKey = "sk_live_51234567890";

# ✅ 正确做法 - 使用环境变量
const apiKey = process.env.API_KEY;

2. HTTPS 强制重定向

1
2
3
4
5
6
7
8
9
{
  "redirects": [
    {
      "source": "http://yourdomain.com/(.*)",
      "destination": "https://yourdomain.com/$1",
      "permanent": true
    }
  ]
}

备份和恢复策略

1. 数据备份

1
2
3
4
5
6
# 定期备份源码（推荐使用多个 Git 仓库）
git remote add backup https://github.com/yourusername/hexo-blog-backup.git
git push backup main

# 备份生成的静态文件（可选）
tar -czf backup-$(date +%Y%m%d).tar.gz public/

2. 快速恢复流程

1
2
3
4
5
# 紧急恢复步骤
1. git clone <repository>
2. npm install
3. 重新配置 Vercel 项目
4. 重新配置域名和 SSL

总结

通过本指南，你已经掌握了将 Hexo 博客部署到 Vercel 的完整流程。这个方案的核心优势在于：

核心价值

  1. 零成本方案：完全免费的博客托管解决方案
  2. 自动化部署：Git 推送即自动构建部署，极大提升效率
  3. 全球加速：Vercel CDN 确保全球访问速度
  4. 扩展性强：支持自定义域名、SSL 证书、环境变量等高级功能
  5. 维护简单：无需服务器管理，专注内容创作

关键成功因素

  • 正确的构建配置：Framework Preset 选择和构建命令配置
  • 完整的代码管理：.gitignore 配置和依赖管理
  • DNS 配置准确性：域名解析和 SSL 证书配置
  • 环境变量安全：敏感信息的正确管理方式

持续优化建议

随着博客内容的增长和访问量的提升，建议持续关注以下方面：

  1. 性能监控：定期检查页面加载速度和 Core Web Vitals
  2. 内容优化：图片压缩、代码分割、懒加载等技术应用
  3. SEO 提升：sitemap 维护、结构化数据、内链优化
  4. 用户体验：移动端适配、无障碍访问、加载体验优化

这个部署方案不仅解决了静态博客的托管需求，更为个人博客的长期发展提供了坚实的技术基础。无论你是技术博主、内容创作者还是个人品牌建设者，这套解决方案都能为你的在线影响力建设提供强有力的支撑。