静态博客这事儿我折腾过好几轮，最早用动态后台，后来发现光维护环境和数据库就够喝一壶的，索性彻底转向静态生成。Hexo 是我来回对比之后留下来的那一个：它把 Markdown 渲染成纯 HTML，整个站点就是一堆文件，扔到代码托管平台的静态页服务上就能跑，服务器、数据库、后台登录统统不用管。这套流程的核心价值在于"写作归写作，运维归运维"，你本地敲hexo new写文章，一条命令生成、一条命令推送，剩下的交给平台。这篇内容面向三类人：完全没碰过静态博客的新手、用过 Hexo 但一直被部署和仓库同步折腾的中级用户，以及想把博客源码做版本管理、换电脑不丢数据的老用户。下面从选型、环境、配置、部署同步到问题排查，把我踩过的坑和最终跑通的方案完整摊开。

1. 动手之前的方案选型：为什么是 Hexo 加静态托管

1.1 静态站点与动态博客的取舍逻辑

先把这个决定讲清楚，因为后面所有操作都是围绕它展开的。动态博客的运行链路是"请求进来 → 服务器执行程序 → 查数据库 → 拼页面 → 返回"，好处是评论、后台编辑、实时统计都现成，坏处是你要为一个可能一个月只更新两篇的东西，长期养着一台机器和一个数据库实例，还得盯着程序版本升级和安全补丁。静态博客把这一步彻底砍掉：文章在本地编译成 HTML、CSS、JS 三件套，上传的就是最终产物，访问时平台直接把文件吐给你，没有执行环节。

这个差异带来的实际影响比想象中大。第一是访问速度，静态文件不需要经过任何服务端计算，首字节时间基本取决于平台的就近分发能力；第二是抗压能力，同一篇爆款文章突然来几万访问，动态站可能直接被打挂，静态站只是多传几个文件而已；第三是数据归属，你的全部内容就是一堆 Markdown 文本，存在自己电脑上、自己仓库里，哪天平台不做了，换个托管照样发，不存在"导不出来"的风险。

代价也很明确：没有实时后台，改文章得在本地改完重新生成推送；原生不支持评论、搜索、阅读量这类需要服务端的功能，得靠第三方组件或静态化方案补；每次发布是一次全量或增量编译，文章多了之后生成时间会线性增长。这三点能不能接受，基本就决定了你适不适合走这条路。

1.2 Hexo 在同类工具里的位置

静态博客生成器不止一个，同类里有偏 Go 的单二进制方案、有偏 Ruby 的老牌方案、也有前端框架衍生的方案。我最后留在 Hexo 上，主要看三点：一是生态成熟度，主题和插件数量足够多，遇到问题搜到的答案大概率对得上；二是写作体验，hexo new建文件、Front-matter 写元信息、hexo s本地预览，链路短；三是它对非前端出身的人足够友好，配置文件是 YAML，改主题基本靠改配置而不是改代码。

需要提醒的是，Hexo 本质是 Node.js 应用，它的所有依赖都走 npm 生态。这意味着你的 Node 版本、包管理器行为会直接影响构建结果，后面环境准备那一章我会专门讲版本对齐，这是新手翻车率最高的地方。

1.3 一套完整方案需要哪些组件

把整条链路拆开看，一个能长期用的 Hexo 博客由四层构成，我在动手前会先把这四层对应到具体工具，避免做到一半发现缺东西。

这张表看着简单，但第二层和第四层的"同源"是这套方案最舒服的地方：代码托管平台既是你的源码仓库，又能直接对外提供页面，一次推送同时完成备份和发布。后面第四章的双仓库同步就是围绕这个特性设计的。

注意：不同平台对静态页服务的开放程度不一样，有的需要手动开启、有的对仓库公开性有要求、有的对构建频率有限制。选平台之前先确认它的静态页功能当前是否可用、有没有额外条件，别等配置全写完了才发现开不了。

2. 从零搭起本地写作环境

2.1 Node.js 版本选择与安装要点

Hexo 官方对 Node 版本有最低要求，装之前先去官网确认当前推荐版本，别凭印象装。我一般选当前长期支持版（LTS）而不是最新特性版，原因很直接：Hexo 的大量依赖是几年前发布的包，遇到 Node 大版本跳跃时，某些包里的原生模块可能编译失败，报错信息还特别难懂，通常是一长串 node-gyp 相关的输出。

安装时有两个细节值得留意。一是安装路径别带中文和空格，Node 的某些子工具对非 ASCII 路径处理得不好，后面跑构建脚本容易莫名其妙失败；二是装完立刻验证，不要跳过这一步。

node -v npm -v

两条命令都正常输出且版本号符合要求，才算环境就绪。如果node -v有输出但npm -v报错，多半是安装时没勾选把 npm 加入环境变量。

包管理器方面，npm 自带够用，也可以换成更快的第三方客户端，但要注意锁文件格式差异。如果你打算把项目源码提交到仓库，锁文件一定要一起提交，否则换台机器装出来的依赖树可能完全不同——这是"本地好好的，换电脑就构建失败"的经典成因。

实操心得：如果npm install卡在某个包上下不动，先换镜像源再重试，比反复删node_modules有效得多。国内访问官方源偶尔会慢，配置一个就近的镜像源能省很多等待。

npm config set registry <就近的镜像源地址> npm config get registry

改完记得用get确认一下，有时候配置写错文件了但命令不报错，实际没生效。

2.2 Git 身份配置与密钥准备

Hexo 的部署插件在底层就是执行 Git 推送，所以本地 Git 必须能免交互地完成推送，否则每次hexo d都要你输密码。这里要区分两种推送方式：走 HTTPS 的需要凭据管理，走 SSH 的需要密钥对。

我固定用 SSH，因为一次配置长期有效。生成密钥对：

ssh-keygen -t rsa -b 4096 -C "博客部署密钥"

一路回车即可，然后把公钥内容（~/.ssh/id_rsa.pub）完整复制，粘贴到代码托管平台的 SSH 公钥设置里。注意复制的是公钥，.pub结尾那个文件，私钥绝对不能外传，也不建议提交到任何仓库。

配置完用一条命令验证连通性：

ssh -T git@<平台域名>

第一次连接会问你确认主机指纹，输入 yes。看到带用户名的欢迎语就说明通了，如果提示权限被拒（Permission denied），通常是公钥没粘全或者粘错了行。

同时把全局身份配好，否则提交记录里的作者信息会是默认值：

git config --global user.name "你的名字" git config --global user.email "你的邮箱" git config --global core.autocrlf false

最后那条core.autocrlf false是我踩坑之后加的。Windows 下默认会把换行符转换，配置文件和 Markdown 混着改的时候容易出现整文件 diff 变红的情况，关掉省心。

2.3 Hexo 初始化与目录结构初勘

环境齐了就开始建站。先全局装命令行工具，再初始化站点：

npm install -g hexo-cli hexo init blog-demo cd blog-demo npm install

hexo init会把模板文件拉下来，npm install才是真正装依赖。这两步顺序不能反，我见过有人直接npm i hexo然后在空目录里敲命令，结果当然是找不到配置。

初始化完成后目录长这样，每个目录的职责必须弄清楚，后面调配置全靠它：

blog-demo/ ├── _config.yml 站点主配置 ├── package.json 依赖清单 ├── scaffolds/ 新建文章的模板 ├── source/ 内容源 │ ├── _posts/ 文章正文 │ ├── _drafts/ 草稿 │ └── about/ 独立页面 ├── themes/ 主题 ├── public/ 生成产物（自动创建） └── .deploy_git/ 部署中转目录（自动创建）

关键认知：只有source/和_config.yml、themes/是你要亲手维护的，public/和.deploy_git/是构建产物，永远不要手动改，也不要提交到源码仓库。很多人第一次提交把public/也塞进仓库，导致仓库体积膨胀、diff 一团乱，后面清理相当麻烦。

2.4 首次本地预览与端口排查

生成并启动本地服务：

hexo generate hexo server

浏览器打开http://localhost:4000能看到默认主题的首页，说明链路通了。如果打不开，先看终端有没有报错，再按这个顺序排：

• 端口被占用：换端口hexo server -p 4001
• 页面空白但控制台 200：多半是主题资源路径错，检查_config.yml里的url和root
• 修改后不生效：先hexo clean再重新生成

hexo clean这个命令要养成习惯。它会清掉public/和缓存数据库db.json。Hexo 有增量生成的缓存机制，改主题、改配置、换插件之后缓存经常对不上，表现就是"我明明改了怎么还是老样子"。我的规则很简单：只要不是改文章正文，一律先 clean 再 generate。

3. 主题、插件与站点配置的实操调优

3.1 _config.yml 里真正需要改的字段

配置文件看着字段多，实际必须动手的就那么几个，剩下的可以保持默认。我把改动的优先级排了一下：

url和root这两个字段是部署后样式丢失的头号元凶。规则很简单：如果你的站点挂在https://域名/根路径下，root就填/；如果挂在https://域名/子路径/下，root就必须填/子路径/，前后斜杠都不能少。生成器靠这个值拼接 CSS 和图片路径，填错就是整站裸奔——HTML 有了，样式全 404。

permalink我一般用:year/:month/:day/:title/这种带日期的结构，理由是文章多了之后按时间归档更直观，而且日后想换域名不影响路径结构。如果担心中文标题进 URL 出问题，可以配hexo-abbrlink插件生成短哈希，但要提前定，中途换等于全站链接失效。

注意：permalink一改，旧链接全部失效。如果站点已经有外部引用或搜索引擎收录，改动前先做跳转方案，别图一时痛快。

3.2 主题安装与嵌套仓库的坑

主题安装有两种方式：克隆到themes/目录，或者用 npm 安装。我偏好克隆，因为改主题源码方便，出问题也好定位。

cd themes git clone <主题仓库地址> my-theme

克隆完把_config.yml里的theme改成my-theme，目录名和字段值必须逐字符一致，大小写敏感。

这里有个几乎所有新手都会撞的坑，必须重点说：克隆下来的主题目录本身带着.git文件夹，而你的博客根目录也是一个 Git 仓库。当你在博客根目录git add .时，Git 会把themes/my-theme识别成一个嵌套仓库，表现为一个灰色的提交引用，实际文件一个都没进仓库。换台电脑 clone 下来，themes/是空的，构建直接失败。

解决办法有三个，按推荐度排：

1. 删掉主题目录里的.git，让主题变成普通文件夹，随博客仓库一起提交。简单粗暴，缺点是主题更新要手动拉。
2. 用 Git 子模块（submodule）挂载主题。规范，但每次 clone 需要额外初始化命令，对新手不友好。
3. 主题的修改用独立补丁文件维护，主题本体走子模块。适合主题改动量大的场景。

我选第一种，因为我改主题改得不多，能接受偶尔手动更新。删除命令：

rm -rf themes/my-theme/.git

如果是 Windows 命令提示符，用rd /s /q themes\my-theme\.git。删完再用git status看一眼，主题文件应该全部变成正常的待添加文件。

3.3 写作流：Front-matter 与草稿机制

建文章：

hexo new post "文章标题"

会在source/_posts/下生成一个 Markdown 文件，头部带 Front-matter：

--- title: 文章标题 date: 2025-01-01 10:00:00 tags: - 标签一 categories: - 分类一 ---

几个字段的含义要拎清。tags是多对多，一篇文章可以打多个标签，写法和列表一致；categories是多层级的，写- 前端再写- 构建工具会生成父子分类关系，注意它是按缩进层级解析的，不是随意写两个就行。date如果不写，Hexo 会用文件创建时间兜底，但建议显式写，避免复制文件导致时间混乱。

草稿机制特别值得用。写一半的文章先扔草稿区：

hexo new draft "半成品"

草稿默认不会被生成，本地预览时加参数才能看到：

hexo server --draft

写完了转正：

hexo publish draft "半成品"

文件会从_drafts/移到_posts/。这个流程的好处是仓库里不会出现半截内容，公开站点永远是完整状态。

实操心得：文件名尽量用英文或拼音，别用中文和空格。虽然现代工具链对中文支持不错，但在 URL 生成、图片引用路径、某些插件处理上仍然偶发问题。标题可以写中文，文件名保持干净。

3.4 常用插件与"能不加就不加"的原则

插件生态是 Hexo 的优势，也是拖慢构建的元凶。我的态度是：只装解决真实痛点的，不装"看起来有用"的。下面这几个是我长期保留的：

安装方式统一是npm install <包名> --save，注意加--save让依赖写进package.json，否则换机器又要凭记忆重装一遍。

要警惕的是那种"装了就变慢"的插件，比如在生成阶段做图片压缩、做全文加密处理的，文章一多，每次构建都要多花几十秒。我的做法是：这类重活儿放在专门的脚本里一次性跑完，不挂在构建钩子上。构建速度直接影响写作欲望，等两分钟才看到预览，写东西的节奏就断了。

4. 部署：把静态文件同步到代码托管仓库

4.1 先搞清楚仓库类型，别一上来就配错

代码托管平台的静态页服务，通常按仓库命名分成两种模式，配置差异很大，搞错了就是白忙活。

用户页模式：仓库名和账号名完全一致，页面地址是根路径。这种模式下生成的文件要推到默认分支，访问地址不带子路径，root填/。

项目页模式：仓库名随便起，页面地址带仓库名子路径。文件推到专门的分支（常见是gh-pages或master，看平台约定），访问地址形如https://域名/仓库名/，此时root必须填/仓库名/。

这两种模式最直观的区别就是root。我见过太多"部署成功但页面全白"的案例，最后都是项目页却把root写成了/。判断方法很简单：看你的最终访问地址里，域名后面有没有一段子路径。

4.2 部署插件配置逐行拆解

先装插件：

npm install hexo-deployer-git --save

然后打开站点_config.yml，找到deploy段，改成这样：

deploy: type: git repo: git@平台域名:用户名/仓库名.git branch: gh-pages message: "站点更新: {{ now('YYYY-MM-DD HH:mm:ss') }}"

四行配置，每一行都有讲究。

type固定写git，这是插件注册的部署器名称，写错了会提示找不到部署器。

repo用 SSH 地址还是 HTTPS 地址决定了推送时要不要交互。用 SSH 地址（形如git@...）配合前面配好的密钥，推送全程无交互；用 HTTPS 地址则可能需要凭据缓存。我统一用 SSH，省去每次输密码。

branch填平台约定的部署分支。注意不同平台约定不同，有的用gh-pages，有的直接用master。填之前先确认平台文档，别照抄别人的配置。

message是提交信息，可以用模板变量插入时间戳。加时间戳的好处是让每次部署的提交记录可追溯，哪天发现线上内容和本地不一致，翻提交历史一眼就能看出哪次部署出了问题。

配置文件里还有一个容易忽略的地方：_config.yml顶部的url字段和deploy.repo必须指向同一个仓库。我见过有人url写着旧仓库地址，repo指向新仓库，结果 RSS 里的链接全指向一个已经不存在的站点。

4.3 双仓库同步：源码私有，页面公开

这是整套方案里我最想强调的部分。很多人的做法是：博客源码不纳管，只有生成后的页面在仓库里。后果是换电脑、误删目录、硬盘故障，全部文章一次性蒸发——这不是危言耸听，我身边真发生过。

正确做法是两套仓库：

• 源码仓库（建议私有）：存_config.yml、package.json、source/、scaffolds/、themes/（无.git）。这是你的全部家当。
• 发布仓库（必须公开或平台允许静态页访问）：存public/里的生成产物，由部署插件自动推送，你不需要手动管理。

源码仓库的.gitignore建议这样写：

node_modules/ public/ .deploy_git/ db.json *.log

node_modules不提交是因为体积巨大且可由package.json重建；public和.deploy_git是产物；db.json是增量缓存，提交了反而会在换机器后造成生成异常。

初始化并推送：

git init git add . git commit -m "初始化博客源码" git remote add origin <源码仓库地址> git push -u origin master

日常写作的完整闭环就变成了三条命令：

git add . git commit -m "新增文章: 某某标题" git push hexo clean && hexo generate && hexo deploy

前三条管源码备份，最后一条管线上发布。两条线独立，哪条出问题都不影响另一条。我习惯把最后一条写成脚本，避免每次手敲漏掉clean。

#!/bin/bash set -e hexo clean hexo generate hexo deploy git add . git commit -m "部署更新 $(date '+%Y-%m-%d %H:%M')" git push

set -e的作用是任何一步失败就中断，避免生成失败了还继续执行部署，把空目录推上去覆盖线上内容——这个事故我亲自制造过一次，线上白屏了半小时才发现。

注意：源码仓库设为私有后，主题如果用子模块方式挂载，克隆时可能因为权限问题失败。这种情况下要么把主题改成普通目录提交，要么确保部署密钥有对应仓库的读取权限。

4.4 部署后的验证清单

推送完成不等于部署成功。平台通常需要一点时间处理，处理完之后按这个清单逐项过：

1. 首页能否打开，样式是否正常加载
2. 随便点开一篇文章，URL 结构是否符合permalink设定
3. 图片能否显示（相对路径是否被正确处理）
4. 站内搜索、RSS、站点地图等附加功能是否返回正常
5. 手机端访问布局是否错乱

如果首页正常但文章 404，多半是permalink改了但旧产物没清；如果首页白屏但源码是 HTML，基本锁定root配置错。这两类问题的排查路径完全不同，别混在一起猜。

5. 常见问题与排查实录

5.1 部署后样式丢失、页面全白

这是出现频率最高的问题，我把成因按概率排了序。

第一位是root配置。项目页部署却没设root，生成的 HTML 里 CSS 路径是/css/style.css，而实际文件在/仓库名/css/style.css，浏览器当然 404。打开开发者工具看 Network 面板，如果一片红色 404，几乎可以确诊。

第二位是url配置。这个字段影响绝对路径的生成，包括站点地图、RSS、以及部分主题里的分享链接。填错的直接表现是功能能用但链接指向别处。

第三位是主题资源没跟着提交。有些主题把静态资源放在自己的source/目录下，克隆时如果走了嵌套仓库那条坑，资源文件根本没进仓库，本地看着正常（因为本地有文件），部署上去就缺资源。

排查顺序建议：先看 Network 面板定位 404 的具体路径，再对照_config.yml的root反推正确值，最后确认主题资源是否完整。这套顺序能覆盖九成情况。

5.2 推送被拒、权限报错的几种典型

推送环节的报错信息往往很直接，但新手容易慌。我把常见的几种列出来：

non-fast-forward这个在双仓库方案里特别容易遇到：你在网页端手动改过一次文件，本地又提交了一次，两边分叉了。处理方式是先拉取合并再推送，别直接强推（--force），强推会把远端别人（或者另一个设备的你）的提交抹掉。

实操心得：多设备写作时，养成"动笔前先 pull"的习惯。我吃过一次亏，在办公室电脑写了一篇，回家用笔记本又写了一篇，两边都推，结果一台机器的提交被覆盖，幸好本地文件还在。

5.3 本地正常、线上异常这类"玄学"问题

有一类问题最耗时间：本地hexo s完全正常，部署上去就不对。原因通常藏在三个地方。

一是缓存。本地的db.json记录了增量生成的中间状态，换环境后缓存对不上，生成结果就不同。解决办法是hexo clean后全量重新生成，别依赖增量。

二是依赖版本漂移。package.json里的版本号如果带^前缀，不同时间安装可能拿到不同的小版本，行为差异就此产生。要彻底解决就提交锁文件，让每次安装的依赖树一致。

三是大小写敏感。Windows 和部分系统对文件名大小写不敏感，本地引用Image.PNG和image.png都能找到，部署到区分大小写的环境就断链。这个问题排查起来极其折磨，因为你本地永远复现不了。预防办法是统一命名规范，图片一律小写加短横线。

5.4 一张速查表收尾

把上面这些整理成一张能直接对照的表，出问题先在这里找一遍，能省掉大量搜索时间。

还有一类问题值得单独提一句：文章越写越多之后，构建时间从几秒涨到几十秒甚至几分钟。这时候先看是不是装了什么在生成阶段做重活的插件，把它们摘掉或改成独立脚本，通常能立竿见影。其次看图片，大图直接扔进source/会让仓库和构建都变重，我的做法是图片走外部图床或者单独的对象存储，仓库里只留链接。

6. 长期维护的几点个人做法

6.1 备份节奏与写作习惯

我的备份节奏是"写完就推"。一篇文章写完、本地预览确认没问题，先提交源码仓库再部署，顺序不能反。原因是部署动作会触发一次完整的生成和推送，如果源码没先备份，而部署过程出了问题（比如网络中断、插件异常），你可能处在一个"线上是旧的、本地是新的、但新内容还没入库"的尴尬状态。

另外我会定期做一次"冷备份"：把源码仓库完整克隆到一个外部存储，一年也就几次。版本控制能防误删，但防不了仓库本身被误操作删除，多一层保险成本很低。

写作习惯上，我坚持草稿区写作，不直接在_posts/里改半成品。原因前面说过，但还有个隐性好处：草稿不会被生成，所以你写一半的时候完全不用担心哪天手滑部署把半成品推上线。

6.2 换电脑与迁移的完整动作

换设备是检验这套方案是否合格的唯一标准。完整流程如下：

git clone <源码仓库地址> blog-demo cd blog-demo npm install hexo clean hexo server

四步能起来就说明方案是健康的。如果起不来，排查顺序是：Node 版本是否与package.json里的引擎要求匹配、themes/目录是否为空、_config.yml里的url和root是否还指向正确位置。

这里要再强调一次主题那个坑。如果当初没删主题目录的.git，克隆下来themes/一定是空的，hexo server会提示找不到主题模板。这时候不用慌，重新克隆一次主题并把.git删掉，然后补一次提交，问题就永久解决了。

6.3 后续可以扩展的方向

这套基础跑通之后，能加的东西不少，但我不建议一次全上。我的经验是每加一个功能就跑一次完整部署验证，确保出问题能定位到具体那一次改动。

值得优先考虑的几个方向：域名绑定（把平台分配的地址换成自己的，注意配置后url字段要同步更新）、评论组件（选静态化方案，避免引入服务端依赖）、访问统计（选轻量脚本，别引入拖慢首屏的大文件）、内容归档页与标签页（大部分主题自带，改配置即可）。这些都属于加完就不太需要维护的部分，性价比高。

至于那些需要持续投入的功能，比如全文检索服务、图片自动压缩流水线，我建议等你确实感到痛了再上。工具是服务于写作的，别让维护博客本身变成一件比写博客还累的事——这是我折腾好几轮之后最实在的体会。