前言

博客之前用 Hexo + GitHub Pages 搭建，用了几年下来积累了一些痛点：

Hexo 的问题：

主题定制困难：Hexo 的模板引擎（EJS/Pug）和样式体系比较老旧，想做深度定制需要大量 hack 主题源码，改完之后升级主题又是灾难
开发体验差：没有热更新，改个样式要重启 server；没有组件化，模板里全是 if/else 逻辑
构建速度慢：文章数量多了之后，hexo generate 越来越慢，100 多篇文章要等好一会儿
GitHub Pages 部署繁琐：需要手动 deploy 或者配置 GitHub Actions，CI 配置本身就容易出问题
生态萎缩：好用的插件越来越少，很多已经停止维护

为什么选 Next.js + Vercel：

React 组件化：UI 用 JSX/TSX 写，和写前端项目一样自然，复用和维护都方便
Tailwind CSS：原子化 CSS，写样式快，不需要在多个文件之间跳来跳去
Contentlayer：Markdown 内容有类型安全，frontmatter 字段编译期就能检查
Vercel 一键部署：推代码自动部署，零配置 CI/CD，自带 CDN 和 HTTPS
社区活跃：Next.js 生态庞大，遇到问题基本都能找到解决方案

最终效果：基于 tailwind-nextjs-starter-blog 模板，定制了暗色 B2 玻璃风格主题，支持分类导航、背景纹理、代码高亮等特性。

项目初始化

Fork 模板

直接从 GitHub fork timlrx/tailwind-nextjs-starter-blog，然后 clone 到本地。

安装依赖

npm install

注意： 模板默认使用 yarn，但如果想统一用 npm，需要做以下清理：

删除 yarn.lock、.yarnrc.yml、.yarn/ 目录
从 package.json 中移除 packageManager 字段
lint-staged 配置中的 yarn 改为 npx

添加 .npmrc

Vercel 构建时 pliny 和 kbar 有 peer dependency 冲突，需要添加 .npmrc：

legacy-peer-deps=true

本地开发

npm run dev

访问 http://localhost:3000 查看效果。

内容配置

站点信息

编辑 data/siteMetadata.js，修改以下关键字段：

title: '你的站点名称',
headerTitle: '你的站点名称',
author: '你的名字',
description: '站点描述',
language: 'zh-cn',
locale: 'zh-CN',
siteUrl: 'https://yourdomain.com',
github: 'https://github.com/yourname',

导航栏

编辑 data/headerNavLinks.ts：

const headerNavLinks = [
  { href: '/', title: 'Home' },
  { href: '/blog', title: 'Blog' },
  { href: '/about', title: 'About' },
]

作者/About 页面

编辑 data/authors/default.mdx，首页 About 卡片和 /about 页面共用这个文件：

---
name: 你的名字
avatar: /static/images/head.png
occupation: 你的职业
github: https://github.com/yourname
---

你的个人介绍，支持多段落。首页显示前两段，/about 页面显示全部。

文章 Frontmatter

每篇文章的 md 文件头部需要包含以下字段：

---
title: '文章标题'
date: 2026-05-12
categories: tech
tags: [标签1, 标签2]
summary: '文章摘要'
---

支持的全部字段：

| 字段 | 必填 | 说明 | | ------------ | ---- | -------------- | | title | 是 | 文章标题 | | date | 是 | 发布日期 | | categories | 否 | 分类（字符串） | | tags | 否 | 标签列表 | | draft | 否 | true 则不发布 | | summary | 否 | 列表页摘要 | | lastmod | 否 | 最后修改日期 | | images | 否 | 封面图 | | top | 否 | true 置顶 |

Vercel 部署

连接仓库

登录 Vercel
点击 "New Project"
导入你的 GitHub 仓库
Framework Preset 选择 Next.js
直接点 Deploy

Vercel 会自动识别 Next.js 项目，执行 npm install && npm run build。

自定义域名

在 Vercel 项目 Settings → Domains 中添加你的域名。

然后在域名服务商（以阿里云为例）配置 DNS：

| 记录类型 | 主机记录 | 记录值 | | -------- | -------- | ------------------------- | | CNAME | www | 你的项目.vercel-dns.com | | A | @ | 76.76.21.21 |

配置完成后，Vercel 会自动为域名申请 SSL 证书。

如果同时想让 裸域名 和 www 都能访问，可以在 Vercel Domains 设置里将其中一个设为重定向到另一个。

踩坑记录

1. Windows 平台锁文件被意外提交

node_modules 里可能包含 .node 等二进制文件，如果用百度网盘/OneDrive 同步项目目录，这些文件可能被损坏或锁定。建议：

项目目录不要放在云同步盘内
或者把 node_modules 加入同步排除列表

2. yarn → npm 切换

模板默认用 yarn。如果切到 npm：

删除所有 yarn 相关文件
package.json 里移除 packageManager
.husky/pre-commit 和 lint-staged 里的 yarn 改成 npx
添加 .npmrc（见上文）

3. @next/swc-win32-x64-msvc 被误提交

这是 Windows 平台专用的 SWC 二进制文件。如果出现在 package.json 的 dependencies 里，Vercel 的 Linux 环境会构建失败。确保这个包不在 dependencies 中。

4. Vercel 部署被 Blocked（Vercel Authentication）

Vercel 开启了 "Vercel Authentication" 保护后，会检查 git commit 的 author email 是否属于关联的 GitHub 账号。如果本地 git 配置的邮箱和 GitHub 绑定的邮箱不一致，部署会被 Blocked。

解决方案：

方案一：在 GitHub Settings → Emails 中添加本地 git 使用的邮箱
方案二：修改本地 git 配置，使用 GitHub 已绑定的邮箱

# 查看当前配置
git config user.email

# 修改为本仓库的提交邮箱
git config user.email "你的GitHub绑定邮箱"

修改后需要新的 commit 才会生效。可以推送一个空提交触发重新部署：

git commit --allow-empty -m "chore: trigger vercel deploy"
git push origin main

5. CSS 背景图只在 Dark 模式生效

如果背景图写在 html.dark body.site-shell 选择器下，当用户的系统主题为浅色时，背景图不会显示。

解决方案： 把背景规则从 dark-only 改为通用规则，所有主题都显示背景图。

6. .next 缓存损坏

开发过程中频繁修改 CSS 后，可能出现样式不更新或 404 的情况。这是 .next 缓存损坏导致的。

# 删除缓存并重启
rm -rf .next
npm run dev

7. Contentlayer 缓存过期

修改了 data/authors/default.mdx 等数据文件后，dev server 可能还显示旧数据。需要重启 dev server 让 contentlayer 重新生成。

8. dev-log.txt 文件被占用

如果在开发时把 npm run dev 的输出重定向到文件（例如 npm run dev > dev-log.txt 2>&1），这个文件会被进程持续占用，导致 git 操作失败。

建议把这个文件加入 .gitignore：

dev-log.txt

一键推送

在项目根目录创建 push.bat，双击即可自动提交推送：

@echo off
cd /d "%~dp0"
git add -A
for /f "tokens=*" %%i in ('powershell -command "Get-Date -Format 'yyyy-MM-dd HH:mm'"') do set msg=%%i
git commit -m "update %msg%"
git push origin main
echo.
echo Done - pushed at %msg%
pause

总结

整个流程的核心步骤：

Fork 模板 → 本地安装依赖
修改站点配置（siteMetadata、导航、作者信息）
添加/迁移文章内容
定制主题样式
连接 Vercel 部署
配置自定义域名
推送代码自动触发部署

Vercel 的体验确实比 GitHub Pages 好很多，推送即部署，不需要额外配置 CI。主要踩坑点集中在 Windows 平台兼容性、npm/yarn 切换、和 Vercel 的提交身份校验上。

Vercel

Categories

用Vercel搭建Next.js博客的完整流程与踩坑记录