1. 为什么我劝你用自己的电脑搭一个博客很多人第一次听到“搭建博客”这四个字脑子里浮现的是买服务器、配数据库、写后端接口这一整套重活。我当年也是这么想的结果拖了两年都没动手。直到有一次我把一篇写了三天的技术笔记误删在某个第三方平台上连回收站都找不回来我才下定决心内容必须放在自己能掌控的地方。Hexo 这个方案是我试过五六种静态博客框架之后留下来的。它的核心逻辑特别简单——你在本地用 Markdown 写文章一条命令生成一堆 HTML 静态文件再把这些文件推到 GitHub Pages 上全世界就能访问了。整个过程不需要服务器、不需要数据库、不需要运维一年下来零成本。对于零基础的人来说这是目前门槛最低、坑最少的一条路。这篇文章我打算把从装环境到线上访问的每一步都拆开讲包括我踩过的那些坑。你不需要懂前端不需要懂 Git 的深层原理只要跟着敲命令就行。适合的人群很明确想有个自己地盘的写作者、想练手的前端新手、想给简历加个作品集的学生以及所有受够了平台审核和广告的人。2. 动手之前先把这几件事想清楚2.1 Hexo 到底是个什么东西用生活化的说法Hexo 就是一个“文章加工厂”。你给它原料Markdown 文件它按你设定的模板主题加工成成品HTML/CSS/JS 文件。这些成品是纯静态的意味着任何人访问你的博客服务器只是把现成的文件丢过去不需要现场计算所以速度极快也几乎不会被攻击。它基于 Node.js 运行所以你的电脑上必须先有 Node.js 环境。这一点很关键很多新手卡在第一步就是因为 Node.js 版本太老或者装错了地方。Hexo 本身是一堆 JavaScript 脚本的集合通过命令行工具hexo-cli来调用。2.2 为什么选 GitHub Pages 而不是别的静态文件生成出来总得找个地方放。GitHub Pages 的好处是免费、稳定、自带 HTTPS、和 Git 工作流无缝衔接。你只需要一个 GitHub 账号建一个特定名字的仓库把生成的文件推上去它就自动帮你托管。这里有个细节要提前说清楚GitHub Pages 有两种仓库类型。一种是用户名.github.io这种仓库每个账号只能有一个访问地址就是https://用户名.github.io适合做主站。另一种是普通仓库开启 Pages 功能访问地址会带子路径。新手建议直接用第一种省去配置子目录的麻烦。2.3 你需要准备的工具清单在正式开始之前把下面这些东西准备好能省掉后面反复中断去下载的时间一台能上网的电脑Windows、macOS、Linux 都行我用的是 Windows 和 macOS 双端命令基本通用Node.js 安装包去官网下 LTS 版本别下最新版LTS 更稳Git 客户端Windows 下装 Git for Windows 就行macOS 自带一个 GitHub 账号没有的话花两分钟注册一个趁手的文本编辑器VS Code 是首选写 Markdown 体验很好一个能科学管理时间的耐心第一次配置大概需要 40 分钟注意Node.js 安装时记得勾选“Add to PATH”否则命令行里找不到 node 命令。Windows 用户如果之前装过旧版本建议先卸载干净再装新的。3. 本地环境搭建的完整实操3.1 Node.js 和 Git 的安装验证装完 Node.js 之后打开命令行Windows 用 PowerShell 或 CMDmacOS 用终端输入下面两行命令验证node -v npm -v正常的话会分别输出类似v18.17.0和9.6.7的版本号。如果提示“不是内部或外部命令”说明 PATH 没配好重新安装并勾选 PATH 选项。Git 的验证命令是git --version输出git version 2.x.x就对了。Git 的作用是帮你把本地文件同步到 GitHub后面会频繁用到。3.2 安装 Hexo 命令行工具Node.js 自带的 npm 是包管理器我们用它来装 Hexo 的命令行工具。在命令行里执行npm install -g hexo-cli-g表示全局安装装完之后在任何目录下都能用hexo命令。装完验证一下hexo -v会输出 hexo-cli 的版本以及它依赖的一些组件版本。这一步如果卡住不动大概率是网络问题可以换用国内镜像源npm config set registry https://registry.npmmirror.com然后再重新执行安装命令。这个镜像源是国内维护的速度会快很多装完之后可以再切回官方源也可以一直用着不影响功能。3.3 初始化你的博客项目找一个你放代码的目录比如D:\projects或者~/Documents然后执行hexo init my-blog cd my-blog npm install第一行命令会创建一个叫my-blog的文件夹里面是 Hexo 的骨架文件。第二行进入这个文件夹。第三行安装项目依赖这一步会下载不少东西耐心等一两分钟。初始化完成后目录结构大概是这样目录/文件作用_config.yml全站配置文件改标题、作者、主题都在这里source/_posts你写文章的目录Markdown 文件放这里themes主题目录默认带一个 landscape 主题public生成后的静态文件部署时推的就是这个目录scaffolds新建文章的模板package.json项目依赖清单3.4 本地预览跑起来在项目根目录执行hexo server或者简写hexo s。命令行会提示Hexo is running at http://localhost:4000。打开浏览器访问这个地址就能看到默认的博客页面了。这时候你看到的是一篇 Hello World 示例文章说明本地环境已经完全通了。提示hexo server启动的服务会监听文件变化你改了文章保存后刷新浏览器就能看到效果不用重启。按CtrlC停止服务。4. 写第一篇文章并理解 Hexo 的工作流4.1 新建文章的两种方式Hexo 新建文章的命令是hexo new 我的第一篇文章执行后会在source/_posts下生成一个我的第一篇文章.md文件。打开它开头是一段被---包裹的内容这叫 Front-matter用来声明文章的元信息--- title: 我的第一篇文章 date: 2024-01-15 10:30:00 tags: categories: ---title是标题date是发布时间tags和categories分别是标签和分类可以留空也可以填。Front-matter 下面的正文部分就用 Markdown 语法写。另一种方式是直接在source/_posts目录里手动新建.md文件但必须自己补上 Front-matter否则 Hexo 可能不识别。我习惯用命令生成省事。4.2 Markdown 写作的几个实用技巧Markdown 语法本身很简单但有几个细节新手容易忽略标题用#到######注意#后面要加空格代码块用三个反引号包裹并标注语言比如python图片引用用路径建议用图床或者放在source/images目录下换行要空一行否则渲染出来会连在一起我个人的习惯是每篇文章写完后先在本地hexo s预览一遍确认排版没问题再部署。因为 Markdown 在不同渲染器下表现有差异Hexo 用的是 hexo-renderer-marked有些语法它支持得和别的平台不太一样。4.3 理解 generate 和 deploy 的区别这是新手最容易混淆的地方。hexo generate简写hexo g的作用是把source目录下的 Markdown 和主题模板一起加工输出到public目录生成纯静态的 HTML 文件。这一步只发生在本地。hexo deploy简写hexo d的作用是把public目录里的内容推送到你配置的远程仓库。这一步才涉及网络传输。所以完整的发布流程是hexo clean hexo generate hexo deployhexo clean是清空缓存和public目录避免旧文件干扰。这三条命令我建议每次都按顺序执行尤其是改了主题配置之后不 clean 经常会出现样式错乱。5. 部署到 GitHub Pages 的详细配置5.1 创建 GitHub 仓库登录 GitHub点右上角加号选择 New repository。仓库名必须严格写成你的用户名.github.io比如你的用户名是zhangsan仓库名就是zhangsan.github.io。这个命名规则是 GitHub Pages 的硬性要求写错了访问不了。仓库创建时选择 Public因为 Private 仓库的 Pages 功能在免费账号下有限制。其他选项保持默认点 Create repository。5.2 配置 Git 身份信息在命令行里设置你的 Git 用户名和邮箱这两个信息会记录在每次提交里git config --global user.name 你的用户名 git config --global user.email 你的邮箱邮箱建议用注册 GitHub 时用的那个这样提交记录能正确关联到你的账号。5.3 安装部署插件并修改配置Hexo 默认不带 Git 部署功能需要装一个插件npm install hexo-deployer-git --save然后打开项目根目录的_config.yml找到最下面的 deploy 部分改成这样deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main注意branch这里GitHub 现在默认分支是main老教程里写的是master写错了会推不上去。如果你不确定去仓库页面看一眼默认分支名。5.4 配置 SSH 密钥免密推送用 HTTPS 方式推送每次都要输账号密码很烦。配置 SSH 密钥可以一劳永逸。先生成密钥ssh-keygen -t rsa -C 你的邮箱一路回车会在~/.ssh目录下生成id_rsa和id_rsa.pub两个文件。用文本编辑器打开id_rsa.pub复制里面的全部内容。回到 GitHub点右上角头像Settings左侧找到 SSH and GPG keys点 New SSH key把复制的内容粘贴进去标题随便起保存。验证是否配置成功ssh -T gitgithub.com看到Hi 你的用户名! Youve successfully authenticated就说明通了。然后把_config.yml里的 repo 地址改成 SSH 格式repo: gitgithub.com:你的用户名/你的用户名.github.io.git5.5 执行部署并访问在项目根目录依次执行hexo clean hexo generate hexo deploy部署过程中会提示你输入 yes 确认然后开始推送文件。完成后打开浏览器访问https://你的用户名.github.io应该就能看到你的博客了。第一次部署后可能需要等一两分钟 GitHub 才会生效如果访问 404先别慌等几分钟再刷新。如果一直 404检查仓库名是否写对、分支是否是 main、Pages 功能是否在仓库 Settings 里开启了。6. 常见问题排查与避坑经验6.1 部署报错速查表报错信息可能原因解决方法Permission denied (publickey)SSH 密钥没配好重新生成密钥并添加到 GitHubremote: Repository not found仓库地址写错或没权限检查 repo 地址和仓库是否存在failed to push some refs远程有本地没有的提交执行git pull后再推hexo: command not foundHexo 没装或 PATH 问题重新npm install -g hexo-cli页面样式全乱缓存或路径问题执行hexo clean后重新生成访问 404Pages 未开启或仓库名错检查仓库 Settings 和命名6.2 我踩过的三个真实坑第一个坑是分支名。我最早跟着一篇老教程配了master结果推上去 GitHub 根本不认折腾了半小时才发现默认分支早就改成main了。所以看教程一定要看发布时间超过两年的配置部分要打个问号。第二个坑是主题配置。我换了一个第三方主题改完_config.yml直接部署结果线上样式全乱。后来才知道主题自己的配置文件在themes/主题名/_config.yml和根目录的_config.yml是两回事。改主题相关的东西要去主题目录里改改完必须hexo clean。第三个坑是图片路径。我一开始把图片放在source/images下文章里用相对路径引用本地预览正常部署后图片全裂。原因是 Hexo 生成后的目录结构和 source 不一样。后来改用绝对路径/images/xxx.png就正常了。或者干脆用图床把图片传到图床拿外链最省心。6.3 提升访问速度的几个实用设置GitHub Pages 在国内访问速度一般但有几个办法可以改善。一是给博客加 CDN把静态资源分发到离用户更近的节点。二是压缩图片别传几 MB 的大图。三是选一个轻量主题别用那种加载一堆字体和图标的。另外Hexo 有个hexo-neat插件可以压缩 HTML、CSS、JS减小文件体积。安装后在_config.yml里配置一下就行npm install hexo-neat --save配置项里把neat_html、neat_css、neat_js都开启exclude里排除掉已经压缩过的第三方库文件避免重复压缩出问题。7. 后续可以继续折腾的方向博客跑起来只是起点。接下来你可以换主题Hexo 的主题市场里有几百个免费主题NexT、Butterfly、Fluid 都是口碑不错的。换主题的流程基本就是下载到themes目录改根目录_config.yml里的theme字段然后重新生成部署。还可以加评论系统、加搜索功能、加访问统计。这些都有现成的插件或者第三方服务配置起来不算复杂。我个人的建议是先把写作习惯养起来别一上来就折腾一堆功能最后文章没写几篇配置倒是改了几十遍。域名方面如果你觉得用户名.github.io太长可以买个自己的域名在仓库 Settings 的 Pages 里绑定 Custom domain再去域名服务商那边加一条 CNAME 记录指向你的 GitHub Pages 地址。这样访问www.你的域名.com就能打开博客了。我在实际使用中最大的体会是Hexo 这套流程一旦跑通写文章就变成了一件很纯粹的事——打开编辑器敲 Markdown三条命令推上去。没有后台登录没有编辑器加载没有广告弹窗。这种掌控感是任何第三方平台都给不了的。