[vercel]全流程个人博客搭建

（vercel）全流程搭建个人博客 #

第零步：前置条件与准备工作 #

在开始之前，请确保你已准备好以下三样东西：

你的个人电脑：用于写作、生成博客。
github账号：github
vercel账号：访问 vercel.com，使用 GitHub 账号登录。
一个已购买的域名：例如 yourname.com。我们将用它作为你的博客地址。
可以去spaceship买 6-9 位的数字 xyz 域名，先买一年（4块钱左右），然后在面板里 renew 补满九年，统共50左右。
相关：网站测速

需要在你个人电脑上安装的软件：

Git：用于版本控制和代码管理。
Hugo：博客生成器本体。
一个好用的代码编辑器：推荐 VS Code，它对 Markdown 和终端操作支持都很好。（记事本也可以）

第一步：在你的电脑上（win11），搭建本地博客 (Local) #

一（1）：安装hugo #

先安装 Chocolatey，再安装 Hugo (一劳永逸的推荐方案)

Chocolatey 是 Windows 上的一个“应用商店”，可以用命令来安装和管理软件，非常方便。

1. 安装 Chocolatey 包管理器

以管理员身份打开 PowerShell：在 Windows 的“开始”菜单上点右键，选择“终端 (管理员)”或“Windows PowerShell (管理员)”。
运行安装命令：在弹出的蓝色或黑色窗口中，复制并粘贴以下整段命令，然后按 Enter 键执行：

      Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

等待命令运行完成。期间可能会出现一些黄色的提示文字，这是正常的。当它停止滚动并回到命令提示符时，就表示 Chocolatey 安装成功了。

验证安装：关闭当前的管理员终端窗口，然后重新打开一个新的终端窗口（普通权限即可）。输入 choco -v，如果能看到版本号（例如 1.2.0），就证明 Chocolatey 安装成功！

2. 使用 Chocolatey 安装 Hugo 现在你拥有了 choco 命令，可以执行我们之前失败的步骤了。在新的终端窗口中运行：

choco install hugo-extended

它会自动下载并帮你配置好 Hugo。成功举例👇

C:\ProgramData\chocolatey\lib\hugo-extended\tools
ShimGen has successfully created a shim for hugo.exe
The install of hugo-extended was successful.
Deployed to 'C:\ProgramData\chocolatey\lib\hugo-extended\tools'

Chocolatey installed 1/1 packages.
See the log for details (C:\ProgramData\chocolatey\logs\chocolatey.log).

Enjoy using Chocolatey? Explore more amazing features to take your
experience to the next level at
https://chocolatey.org/compare

3. 最终验证 等待安装完成后，输入以下命令：

hugo version

如果能看到类似 hugo v0.119.0-extended ... 的版本信息，恭喜你，Hugo 已经完美安装成功！

二（2）：创建你的博客网站 #

打开终端，cd 到你希望存放博客代码的目录（例如 D:\Code 或 ~/Documents），然后运行：

hugo new site my-blog

示例：

D:\waiting-blog>hugo new site my-blog
Congratulations! Your new Hugo site was created in D:\waiting-blog\my-blog.

Just a few more steps...

1. Change the current directory to D:\waiting-blog\my-blog.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>\<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.

这会创建一个名为 my-blog 的文件夹，里面包含了 Hugo 网站的标准目录结构。现在，进入这个目录：

cd my-blog

重要提示：之后的所有本地操作，都在这个 my-blog 文件夹内进行。

一（3）、安装一个主题 #

（1）. 以PaperMod 举例 选择一个广受欢迎且配置简单的主题 PaperMod 作为开始。

在 my-blog 目录下，把主题仓库克隆到 themes 文件夹中：

git init # 初始化 git 仓库
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod

示例：

D:\waiting-blog>cd my-blog

D:\waiting-blog\my-blog>git init
Initialized empty Git repository in D:/waiting-blog/my-blog/.git/

D:\waiting-blog\my-blog>git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
Cloning into 'D:/waiting-blog/my-blog/themes/PaperMod'...
remote: Enumerating objects: 7828, done.
remote: Counting objects: 100% (77/77), done.
remote: Compressing objects: 100% (45/45), done.
remote: Total 7828 (delta 63), reused 32 (delta 32), pack-reused 7751 (from 3)
Receiving objects: 100% (7828/7828), 9.60 MiB | 2.94 MiB/s, done.
Resolving deltas: 100% (4608/4608), done.
warning: in the working copy of '.gitmodules', LF will be replaced by CRLF the next time Git touches it

（2）. 配置你的博客 打开 my-blog 目录下的 hugo.toml (或者 config.toml) 文件，这是 Hugo 的主配置文件。将里面的内容 全部替换 为以下内容：

 baseURL = "http://example.org/" #注意改成自己的域名 
 languageCode = "zh-cn"
 title = "我的博客"
 theme = "PaperMod" # <-- 这一行就是最关键的连接！它告诉 Hugo 使用 PaperMod 主题

 [params]
   defaultTheme = "auto" 
   ShowShareButtons = true
   ShowPostNavLinks = true
   ShowReadingTime = true

 [menu]
   [[menu.main]]
     identifier = "archives"
     name = "归档"
     url = "/archives/"
     weight = 10
   [[menu.main]]
     identifier = "tags"
     name = "标签"
     url = "/tags/"
     weight = 20
   [[menu.main]]
     identifier = "search"
     name = "搜索"
     url = "/search/"
     weight = 30

（3）. 撰写你的第一篇文章 在终端中运行以下命令，创建一篇新文章：

hugo new posts/my-first-post.md

这条命令会在 content/posts/ 目录下创建一个名为 my-first-post.md 的文件。示例：

D:\waiting-blog\my-blog>hugo new posts/my-first-post.md

Content "D:\\waiting-blog\\my-blog\\content\\posts\\my-first-post.md" created

用你的编辑器打开它，会看到如下内容：

---
title: "My First Post"
date: 2025-11-17T21:00:00+08:00
draft: true  # 注意这个 draft
---

--- 中间的部分叫做 Front Matter，是文章的元数据。
将 draft: true 改为 draft: false，或者直接删掉这一行，文章才能被看到。
在 --- 下方，用 Markdown 语法写下你的第一篇博客内容。

（4）. 在本地预览你的博客 在终端中运行：

hugo server

Hugo 会启动一个本地服务器。看到类似 Web Server is available at http://localhost:1313/ 的输出后，打开你的浏览器，访问 http://localhost:1313。示例：

D:\waiting-blog\my-blog>hugo server
Watching for changes in D:\waiting-blog\my-blog\{archetypes,assets,content,data,i18n,layouts,static,themes}
Watching for config changes in D:\waiting-blog\my-blog\hugo.toml
Start building sites …
hugo v0.152.2-6abdacad3f3fe944ea42177844469139e81feda6+extended windows/amd64 BuildDate=2025-10-24T15:31:49Z VendorInfo=gohugoio


               │ EN
─────────┼──
Pages            │ 10
Paginator pages  │  0
Non-page files   │  0
Static files     │  0
Processed images │  0
Aliases          │  2
Cleaned          │  0

Built in 19 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

验证环节：如果你能成功看到一个简洁的博客页面，并且上面有你的第一篇文章，那么恭喜你，第一步完美完成！你的博客已经在本地跑起来了。

第二步：本地电脑和 GitHub 备份仓库连接 #

二（1）：在 GitHub 上进行的操作 (准备你的云端备份仓库) #

这一步是为了给你的博客源代码安一个安全的家。

登录 GitHub 官网：打开浏览器，访问 github.com 并登录你的账号。
创建一个新的仓库 (Repository)：
- 点击页面右上角的 + 号，选择 New repository。
- Repository name：给仓库取个名字，比如 my-hugo-blog。
- Description：选填，可以写“我的个人博客源码”。
- 关键选择：选择 Private (私有)。因为你的博客配置里可能包含一些个人信息，所以设置为私有更安全。
- 不要勾选初始化仓库的任何选项（如 Add a README file）。
- 点击 Create repository。
复制仓库地址：创建成功后，页面会显示一些指引。找到 HTTPS 地址，它看起来像 https://github.com/你的用户名/my-hugo-blog.git。点击旁边的复制按钮。

GitHub 上的准备工作到此结束。 它的任务就是提供了一个空的、私有的仓库地址。

二（2）：在你【个人电脑】上进行的操作 (连接本地与 GitHub) #

现在，我们要把你本地的博客文件夹，和你刚刚在 GitHub 上创建的仓库连接起来，并做一次初始备份。

打开终端 (PowerShell 或 CMD)，并 cd 到你的博客根目录 D:\waiting-blog\my-blog。

关联远程仓库：运行以下命令，把 origin 这个默认的远程名指向你的 GitHub 仓库。（请将 URL 换成你上一步复制的地址）

git remote add origin https://github.com/你的用户名/my-hugo-blog.git

如：

D:\waiting-blog\my-blog>git remote add origin https://github.com/你的用户名/my-hugo-blog.git

进行首次提交和推送：把你的博客代码第一次备份到 GitHub。

# 查看分支：git status
# 如果你的主分支不是 master，可能需要先重命名为 main
git branch -M main 

git add .
git commit -m "Initial commit: 我的博客初始化"
git push -u origin main

执行后，刷新你的 GitHub 仓库页面，你就能看到所有本地文件都被上传上去了。

可以检查一下连接状态：

检查一下连接状态，运行：
```
git remote -v
```
你应该能看到一组地址：
- origin 指向 github.com (这是你的备份仓库)

示例：

 D:\waiting-blog\my-blog>git remote -v
origin  https://github.com/你的用户名/my-blog.git (fetch)
origin  https://github.com/你的用户名/my-blog.git (push)

至此，你的本地电脑已经和 GitHub 备份仓库成功连接。

第三步：在vercel部署博客 #

三（1）：GitHub 仓库准备 #

确保你的代码在 GitHub 上是最新且配置正确的。

本地配置检查：
- 打开 config/_default/hugo.toml。
- 关键点：baseURL 必须是你正式的域名，例如 https://xxxx.xyz/（注意 https 和末尾斜杠）。(注意你在vercel的访问域名是什么，有没有www前缀，有就注意改，不然访问很慢)
- 关键点：languageCode 和 defaultContentLanguage 必须一致（建议都设为 zh-Hans）。
解决样式拦截问题（SRI 补丁）：
- 这是为了防止 Cloudflare 缓存导致样式丢失。
- 确保你已经在本地创建了 layouts/partials/head.html。
- 确保该文件里，<link rel="stylesheet" ...> 和 <script ...> 标签中，去掉了 integrity="..." 属性，并且去掉了 | resources.Fingerprint 管道符。

提交最新代码：

git add .
git commit -m "Ready for Vercel deployment"
git push origin main

三（2）：Vercel 项目导入与配置（主体） #

注册/登录：访问 vercel.com，使用 GitHub 账号登录。
新建项目：
- 点击 Add New -> Project。
- 在 Import Git Repository 列表中，找到你的博客仓库，点击 Import。
配置构建环境（关键！防止版本报错）：
- Framework Preset：默认选 Hugo 即可。
- Build Command：默认即可（或者填 hugo --gc --minify）。
- Environment Variables（环境变量）：这一步必须做！
  - 展开 Environment Variables。
  - Key: HUGO_VERSION
  - Value: 0.152.2 (或者是你本地 hugo version 显示的版本，一定要新)。
  - 点击 Add。
开始部署：点击 Deploy。
- 等待几十秒，直到出现满屏撒花的庆祝动画，说明部署成功。

三（3）：域名连接与 DNS 设置（指路） #

Vercel 端添加域名：
- 进入 Vercel 项目 -> Settings -> Domains。
- 输入你的域名（如 example.xyz），点击 Add。
- Vercel 会提示你缺少 DNS 记录，并给出需要的记录值（A 记录或 CNAME）。
Cloudflare 端修改 DNS：
- 登录 Cloudflare -> 点击域名 -> DNS -> 记录。
- 添加新记录：
  - 类型: A | 名称: @ | 内容: Vercel 提供的 IP (如 76.76.21.21) | 代理状态: ☁️ 仅 DNS (灰云) （推荐灰云，最稳定）。
  - 类型: CNAME | 名称: www | 内容: cname.vercel-dns.com | 代理状态: ☁️ 仅 DNS (灰云)。
- 之后操作可以参考：[ Cloudflare上托管SpaceShip域名的方法](Cloudflare上托管SpaceShip域名的方法 | 小布分享站)

三（4）：Cloudflare SSL 兼容设置（排雷） #

如果你在 Cloudflare 上开了橙色云朵（代理模式），或者为了防止出现 Error 526，这一步必须检查。

在 Cloudflare 后台 -> SSL/TLS -> 概述。
将加密模式设置为 “完全 (Full)”。
- ❌ 不要选“灵活 (Flexible)”（会导致无限重定向）。
- ❌ 不要选“完全严格 (Full Strict)”（Vercel 证书未生效前会报错）。

第四步：日常写作与更新流程 #

写作：在本地电脑 content/posts 下新建或修改 Markdown 文章。
预览：在本地终端运行 hugo server，浏览器访问 localhost:1313 查看效果。

发布（只需三行命令）：

git add .
git commit -m "写了一篇新文章"
git push origin main

完事！

你可以关掉终端了。
Vercel 会自动感应到你的 push。
大约 30-60 秒后，你的网站 https://example.xyz 就会自动更新。

🎉 恭喜！ #

你现在拥有的是一个：

xx主题（自己搭配折腾）
秒开（Vercel 全球 CDN）
自动化（Git 驱动）
现代化（Hugo + Congo）的个人独立博客。