Published on

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

Authors
  • avatar
    Name
    东哥
    Twitter

前言

博客之前用 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 部署

连接仓库

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

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

自定义域名

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

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

记录类型主机记录记录值
CNAMEwww你的项目.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

总结

整个流程的核心步骤：

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

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

Discuss on Twitter • View on GitHub