yukiBlogs

给大家分享一下我的博客是怎么搭建的吧

先感谢 XingHuiSama 大佬的开源项目https://github.com/heiehiehi/XinghuisamaBlogs
我的博客在他的基础上进行二次开发而来，修复了部分bug，增加了一些新功能
本项目也开源在https://github.com/T0ka1Teio/yukiBlogs-source（开发中，如果找不到就暂时还是闭源）

‍

接下来介绍如何将本博客部署为可长期维护的个人站点，并完成媒体资源存储、源码托管、云端部署和后续内容发布。

最终的数据流如下：

本地管理端
  ↓ 发布并同步
Next.js 前端源码
  ↓ Git push
GitHub 仓库
  ↓ 自动构建
Vercel 生产环境

Cloudflare R2 ──→ 免费存储桶（10G），存放头像、背景、封面和相册图片
GitHub Issues ──→ 评论数据
Upstash Redis ──→ 访客数和文章阅读次数

1. 准备开发环境

项目包含 Next.js 前端和 Python 管理端，开始前需要安装以下工具：

Git：克隆项目和提交源码
Node.js ≥ 20.9：运行 Next.js 16
Python ≥ 3.10：运行本地管理端
uv：创建和维护 Python 虚拟环境

安装完成后，在 PowerShell 中检查版本：

git --version
node --version
npm --version
python --version
uv --version

如果 node --version 低于 20.9，应先升级 Node.js。Next.js 16 的最低 Node.js 版本要求为 20.9。

2. 克隆开源项目并运行

本项目基于 XinghuisamaBlogs 进行二次开发，原项目地址如下：

https://github.com/heiehiehi/XinghuisamaBlogs

在目标目录执行：

git clone https://github.com/heiehiehi/XinghuisamaBlogs.git
cd XinghuisamaBlogs

完成后重点关注两个目录：

XinghuisamaBlogs\
├─ my-blog-manager\   # 本地内容管理端，不直接部署到公网
└─ XHBlogs\           # Next.js 前端，提交到 GitHub 并部署到 Vercel

更多细节请查看项目README.md

3. 使用 Cloudflare R2 存储图片（图床还没做好，稍后更新）

源码仓库适合保存代码和 Markdown，不适合长期堆积大尺寸图片。可以使用 Cloudflare R2 保存头像、背景、文章封面和相册资源，免费额度就有 10G😋。

3.1 开通 R2

注册并登录 Cloudflare；
进入 Storage & Databases；
选择 R2；
按页面提示开通 R2 服务。

3.2 创建存储桶

进入 R2 控制台后：

点击 Create bucket；
输入存储桶名称，例如 blog-img；
选择默认存储类型；
点击创建。

存储桶名称只能使用小写字母、数字和连字符。

‍

3.3 上传并公开图片

打开刚创建的存储桶；
点击上传对象；
上传头像或文章封面；
进入存储桶的 Settings；
在公共访问区域启用 r2.dev 开发地址，或绑定自己的域名；
复制对象的公开 URL；
将 URL 填入博客控制台的头像、背景或封面字段。

这样你就拥有了一个 R2 图床。如果希望有一个图床管理界面，可以看看项目：https://github.com/MarSeventh/CloudFlare-ImgBed 以及视频教程：https://www.bilibili.com/video/BV1EeNu6zEAe/

4. 创建 GitHub 源码仓库（可以让你的AI帮你做）

在 GitHub 创建一个空仓库。导入已有本地项目时，不要预先创建 README、License 或 .gitignore，以免首次推送出现不必要的历史冲突。

进入前端目录：

cd /myBlogs

初始化并提交：

git init
git add .
git commit -m "feat: initialize customized blog"
git branch -M main
git remote add origin https://github.com/<ACCOUNT>/<REPOSITORY>.git
git push -u origin main

如果仓库已经存在远程地址，先检查：

git remote -v

博客评论建议使用单独的公开仓库，因为基于 GitHub Issues 的评论系统需要访客能够访问 Issue。前端部署仓库和评论仓库承担不同职责。前端部署仓库建议设置私有，评论仓库设置为公开。

5. 在 Vercel 部署 Next.js

5.1 导入 GitHub 仓库

注册并登录 Vercel；
连接 GitHub 账号；
点击 Add New → Project；
选择刚刚推送的前端仓库；# 注意：这里是前端仓库
Framework Preset 选择 Next.js；
其他保持默认，点击Deploy

5.2 配置环境变量（考虑篇幅较长，搞不懂的话让AI带着你做吧）

在项目的 Settings → Environment Variables 中按需添加：

变量用途GEMINI_API_KEYAI 宠物或聊天功能
QWEATHER_KEY天气接口
GITHUB_OAUTH_CLIENT_SECRET GitHub 评论授权
KV_REST_API_URL Upstash Redis REST 地址
KV_REST_API_TOKEN Upstash Redis REST Token
STATS_OWNER_KEY排除站长浏览器的统计密钥

‍

5.3 执行部署

点击 Deploy 后，Vercel 会自动完成：

拉取 GitHub 源码
→ 安装 npm 依赖
→ 执行 next build
→ 创建 Serverless Functions 和静态页面
→ 分配生产访问地址

这样你的博客网站就部署好了✌️✌️

6. 发布第一篇文章

建议统一通过管理端发布文章：

启动 my-blog-manager\Start.bat；
打开文章编辑器；
填写标题、发布日期、标签、摘要和封面；
编写正文并先保存草稿；
点击正式发布，将操作加入队列；
点击“更新本地”； # 同步控制台
点击“同步 Blog”；# 同步本地前端
检查前端 posts 目录已经生成同名 Markdown；
提交并推送 GitHub；# 同步到线上博客
等待 Vercel 自动部署。

7. 常见故障排查

7.1 控制台能看到修改，前端仍是旧内容

依次检查：

是否点击“更新本地”；
是否点击“同步 Blog”；
管理端与前端的同名 Markdown 是否一致；
浏览器是否仍在使用旧页面状态。

如果从外部编辑器直接修改 Markdown，已经打开的控制台不会自动刷新。先重新加载编辑页，再继续发布，避免旧内容覆盖新文件。

7.2 本地正确，线上仍是旧版本

执行：

git status
git log -1 --oneline
git remote -v

然后确认：

修改已经提交；
提交已经推送到生产分支；
Vercel 连接的是同一个仓库和分支；
最新 Deployment 状态为 Ready。

7.3 GitHub OAuth 提示 redirect_uri 不匹配

GitHub OAuth App 中配置的 Authorization callback URL 必须与程序实际发送的回调地址一致，包括：

http 或 https；
域名；
端口；
路径；
末尾斜杠。

本地控制台和线上站点通常需要分别创建 OAuth App，避免两套回调地址互相覆盖。

7.4 修改 Vercel 环境变量后功能仍未恢复

环境变量不会注入已经完成的旧部署。保存变量后进入 Deployments，选择最新生产部署并执行 Redeploy。

7.5 R2 图片可以访问但加载不稳定

检查对象 URL 是否正确、存储桶是否允许公共读取。r2.dev 是开发访问地址，正式站点应优先绑定自定义域名。

8. 结论

一个可维护的博客不只是前端页面，还包括内容源、媒体存储、版本管理、部署环境和外部服务。将这些职责分开后，系统边界会更加清晰：

管理端负责创作和生成内容；
Next.js 前端负责页面与服务端路由；
Cloudflare R2 负责图片等对象存储；
GitHub 负责源码版本管理；
Vercel 负责构建与生产运行；
GitHub Issues 和 Redis 分别承担评论与统计数据。

后续维护时只需要遵循固定发布链路，并在每次上线前完成类型检查、生产构建和线上验证，就能显著降低“本地正常、线上异常”的概率。

参考资料

‍

感谢你看到这里！如果希望和🐷波交个朋友的话欢迎在评论区留下你的友链~