Hexo博客搭建全流程：从GitHub Pages到云服务器部署避坑指南

搭建博客这事我前后折腾了两周把Hexo从本地到GitHub Pages再到自己的云服务器全跑通了一遍。标题里写“坑已踩完”真不是夸张——光是部署这一步我就推倒重来了三次。如果你正准备上手Hexo或者已经在某个环节卡住了这篇文章应该能帮你省下我当初那两周的冤枉时间。先把适用范围说清楚这篇文章适合想用Hexo搭建个人博客、并且希望同时掌握GitHub Pages和云服务器两种部署方式的同学。GitHub Pages免费但不稳定服务器稳定但需要花钱和维护两者我都跑通了各自的坑也会分开讲。你不需要预先掌握什么只要会基本的命令行操作跟着一步步来就能跑完整个流程。1. 先想清楚你需要的到底是GitHub Pages还是服务器很多人一开始就陷入选择困难。我的建议是别纠结两个都配。GitHub Pages用来预览和引流服务器用来做正式站点两者并不冲突。1.1 两种部署方式的核心差异GitHub Pages的定位是“免费托管静态页面”它只能托管纯静态文件不支持后端程序没有数据库也不能执行服务端脚本。Hexo生成的恰好是纯静态HTML文件和GitHub Pages是天作之合。云服务器的定位则是“一台24小时开机的电脑”。你可以在这台“电脑”上装Nginx、配置SSL证书、做301跳转、加防盗链甚至以后想给博客加上评论系统的后端服务都完全可控。我实际对比下来两条路线的体验差异非常明显对比项GitHub Pages云服务器费用免费每年数百元起访问速度国内不稳定时快时慢国内节点可达毫秒级HTTPS证书自动签发无需操心需要自己申请和配置自定义域名支持但需要手动配置CNAME直接解析自由度更高维护成本零维护需要定期更新系统和Nginx拓展性只能托管静态文件可部署后端服务、数据库等1.2 你该怎么选两个我都建议配如果你只是想写写笔记不追求访问速度和域名自由度GitHub Pages完全够用。但如果你有一个正经的域名想让国内访客稳定访问那服务器几乎是必须的。我现在的方案是GitHub仓库作为源文件和备份GitHub Pages作为自动构建的预览站点自己的服务器作为正式站点。每次写完文章执行一条部署命令两个站点会同时更新。后面我会详细讲这个“一条命令双部署”的配置方法。2. 环境搭建Node.js版本和Git配置是第一道坑Hexo的运行依赖Node.js环境。这一步很多教程一笔带过实际上踩坑概率非常高——主要栽在版本不兼容上。2.1 安装Node.js的正确姿势Hexo官方文档对Node.js版本有要求但对新手来说容易忽略。早期版本对高版本Node的兼容性很差如果你直接装最新的Node版本后面可能会遇到编译报错或插件不兼容。我实测下来的稳妥组合是Node.js 16.x或18.x长期支持版配合最新版Hexo。不要盲目追新长期支持版本稳定性和生态兼容性都经过验证。安装完成后用两个命令验证环境node -v npm -v如果这两个命令能正常输出版本号说明Node.js安装成功。如果提示“node不是内部或外部命令”说明环境变量没配置好需要手动把Node.js的安装路径添加到系统环境变量里然后重启终端。2.2 Git安装与初始配置Git是连接本地和远程仓库的桥梁。安装Git后必须配置用户名和邮箱否则后面提交代码会报错git config --global user.name 你的用户名 git config --global user.email 你的邮箱这里有个细节用户名和邮箱不一定非得和GitHub注册信息完全一致但建议保持一致否则GitHub的提交记录会显示成一个陌生的“幽灵用户”。2.3 安装Hexo命令行工具环境就绪后安装Hexonpm install -g hexo-cli执行这条命令可能遇到的问题权限不足、网络超时、镜像源访问慢。权限不足的解决方案是macOS或Linux用户使用sudo前缀Windows用户用管理员权限打开终端。网络超时的解决方案是把npm镜像源切换到国内镜像源速度会快很多npm config set registry https://registry.npm.taobao.org注意不同时期的镜像源可用性有变化。如果配置后发现安装失败可以检查镜像源是否仍然有效或者换回官方源重试。3. 初始化博客hexo init之后你应该做哪几件事环境装好之后初始化和配置阶段也有几个细节需要处理好这些坑我也是踩过的。3.1 初始化命令与目录结构在你想存放博客的目录下执行hexo init my-blog cd my-blog npm installhexo init会拉取Hexo的基础模板npm install会安装模板依赖的插件。这两步都完成后目录结构是标准的Hexo项目结构其中关键的文件和文件夹包括_config.yml是站点的全局配置文件source/_posts存放你的Markdown文章themes目录存放主题。3.2 本地预览验证执行启动预览服务查看默认效果hexo server浏览器访问http://localhost:4000能看到默认的Hexo首页说明本地搭建成功。这个预览服务支持热更新修改文章后刷新页面就能看到效果非常适合写作时实时预览。3.3 写第一篇文章写文章用Markdown格式放在source/_posts目录。我建议先用命令生成模板避免自己建文件时遗漏头部信息hexo new 我的第一篇文章这条命令会在source/_posts下自动生成一个.md文件打开后你会看到头部有title、date、tags等字段这些是Hexo解析文章用的元数据。写完后重新预览全新文章应该已经出现在首页上。这时候本地流程算是跑通了写Markdown → 预览 → 后续生成静态文件 → 部署。4. 部署到GitHub Pages免费方案里面的那些坑GitHub Pages的部署逻辑是把Hexo生成的静态文件推送到一个特殊的Git仓库分支GitHub会自动识别并托管它们。4.1 创建仓库的注意事项在GitHub上创建一个新仓库仓库名必须是你的用户名.github.io这种格式。这个命名规则是硬性的不一致会导致Pages服务无法启用。创建时不要勾选“使用README初始化仓库”。因为后面要用git push推送本地内容如果仓库里已经有初始文件首次推送会要求先合并远程历史对新手来说容易出错。4.2 生成静态文件并部署本地博客目录下执行hexo clean hexo generatehexo clean清理之前生成的静态文件hexo generate根据当前文章重新生成。这两个命令建议每次部署前都成对执行能避免很多缓存导致的不一致问题。然后安装自动部署插件npm install hexo-deployer-git --save编辑_config.yml中的部署配置deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main最后执行部署hexo deploy这条命令会把生成的静态文件推送到GitHub仓库的main分支。首次执行时会要求输入GitHub用户名和密码——注意这里的密码不是登录密码而是Personal Access Token。4.3 GitHub Pages部署踩坑实录踩过的坑主要集中在三个方面。第一分支选择不对。早期教程会建议推送到master分支但新版GitHub默认分支名是main。配置里写错分支名会导致推送成功但Pages服务找不到文件。解决方法是检查仓库的Settings → Pages页面确认Source选项里选择的分支和部署配置里一致。第二强制使用HTTPS导致混合内容报错——如果博客里引用了http开头的图片资源浏览器会拦截请求。解决方法是所有外部资源地址都改成https或者相对路径。第三CNAME文件覆盖。如果你绑定了自定义域名需要在source目录下新建一个名为CNAME的文件内容写你的域名。有个常见的坑是每次部署时CNAME文件被覆盖删除导致域名解析失效。解决方案后面讲服务器部署时会提到也可以把域名解析直接指向服务器然后用服务器统一处理。5. 部署到云服务器完整Web服务的搭建流程到这里GitHub Pages的免费糖已经吃过了。接下来上正菜把博客部署到云服务器上。这部分内容较多涉及Linux基础、Nginx配置、证书签发、进程守护等。5.1 服务器选型与基础环境服务器操作系统我建议选择Ubuntu 22.04 LTS或Debian 12原因是软件仓库比较新安装软件方便网上资料也最多。推荐用“宝塔面板”或直接用命令行操作。我用的是命令行因为后面要配置Nginx和证书命令行更灵活而且能加深理解。如果你不熟悉命令行用面板也能完成同样的配置但需要注意面板自身的安全加固。登录服务器后先执行系统更新apt update apt upgrade -y然后安装Nginx和Gitapt install nginx git -y5.2 服务器端部署方案的选型把Hexo生成的静态文件传输到服务器有几种常见方案我从实际使用的角度分析一下各自的坑。方案一是用hexo-deployer-rsync通过rsync协议同步文件到服务器。这个方案能只增量同步变化的文件部署速度快但服务器上需要额外安装配置rsync服务并且SSH密钥配置不当容易出权限问题。方案二是用Git仓库做中转在服务器上建一个裸仓库本地推送后通过Git钩子把文件同步到Nginx的站点目录。这个方案版本可回退部署过程完全自动化适合有一定Git基础的人。缺点是首次配置钩子脚本时需要小心处理权限和目录路径。方案三是最“暴力”的用hexo-deployer-ftp或SFTP直接上传文件。简单直接但每次全量上传文件多时速度慢而且上传中断可能导致站点文件不完整。我最终选择的是方案一也是实测下来最稳的。原因有三rsync增量同步天然适合静态博客场景配置相对简单不需要维护Git钩子断点续传能力让部署过程更可控。5.3 配置SSH免密登录为了让本地能自动推送文件到服务器需要配置SSH密钥登录。本机生成密钥对ssh-keygen -t rsa -b 4096把公钥上传到服务器ssh-copy-id root你的服务器IP配置完成后本地直接执行ssh root你的服务器IP能免密登录说明配置成功。这里有个关键细节ssh-copy-id会尝试用密码登录一次如果服务器的SSH配置禁止密码登录这一步会卡住需要先在服务器上临时开启密码登录或者手动把公钥追加到服务器的authorized_keys文件里。5.4 安装配置rsync同步工具服务器上安装rsyncapt install rsync -y本地安装部署插件npm install hexo-deployer-rsync --save编辑_config.ymldeploy: - type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main - type: rsync host: 你的服务器IP user: root root: /var/www/hexo port: 22 delete: true注意这里的root字段指服务器上存放博客文件的目录delete: true表示同步时删除服务器上多余的文件保证两边完全一致。执行hexo deploy插件会把public目录下的文件同步到服务器的/var/www/hexo目录。5.5 配置Nginx站点服务器上为博客站点创建Nginx配置vim /etc/nginx/sites-available/hexo-blog写入基础配置server { listen 80; server_name 你的域名; root /var/www/hexo; index index.html; location / { try_files $uri $uri/ 404; } }启用配置并重载Nginxln -s /etc/nginx/sites-available/hexo-blog /etc/nginx/sites-enabled/ nginx -t systemctl reload nginx浏览器访问你的服务器IP能看到博客说明Nginx配置成功。5.6 域名解析与HTTPS证书域名解析到服务器IP后剩下最关键的一步是配置HTTPS证书。我用的是免费证书方案以Lets Encrypt为例apt install certbot python3-certbot-nginx -y certbot --nginx -d 你的域名Certbot会自动修改Nginx配置启用HTTPS并配置自动续期。这里有个实用的细节免费证书有效期一般是90天Certbot会自动配置定时任务续期但你需要确认定时任务真的在运行systemctl status certbot.timer如果定时器没有启用执行systemctl enable certbot.timer systemctl start certbot.timer有个常见坑防火墙没放行443端口导致HTTPS访问不了。如果你的服务器有防火墙需要放行ufw allow 80 ufw allow 443 ufw enable6. 方案升级本地一条命令GitHub Pages和服务器同时更新两种部署方式都跑通后我整合出了一套“一条命令完成双部署”的流程。这里把完整的配置和操作路径拉通讲一遍方便你直接照抄。6.1 完整部署流程编排修改_config.yml的deploy段配置多个部署目标deploy: - type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main - type: rsync host: 你的服务器IP user: root root: /var/www/hexo port: 22 delete: true这样配置后每次需要发布文章时完整执行hexo clean hexo generate hexo deployhexo deploy会按顺序执行两个部署动作先推送到GitHub Pages再同步到服务器。整个过程通常不到一分钟。6.2 配置多仓备份如果你的目标是“不让文章丢失”建议在博客根目录下也初始化一个Git仓库专门用来管理源文件Markdown、主题配置、配置文件git init git add . git commit -m backup git remote add origin https://github.com/你的用户名/my-blog-source.git git push -u origin main这样等于上了双保险源文件和生成的静态文件分别在两个仓库里即使本地电脑坏了也能从远程仓库完整恢复。6.3 自动化部署脚本把发布流程封装成一个脚本文件避免每次都手动敲三条命令#!/bin/bash hexo clean hexo generate hexo deploy给脚本添加执行权限放到系统PATH目录里之后每次写作完毕只需要执行hexo-publish另外Hexo本身提供了“Git钩子”方案在GitHub仓库里配置Webhook推送后自动触发服务器拉取文件更新。这个方案适合想彻底自动化的场景但需要服务器上额外跑一个监听服务后期维护成本高一些——按需选择就好。7. 常见问题与排查技巧实录这里整理我在整个搭建过程中遇到过的典型问题全部实测过按频率从高到低排列附上解决思路。建议直接收藏遇到问题回来翻。7.1 部署类故障故障现象可能原因解决方案push时报错“Permission denied (publickey)”SSH密钥未配置或未加载重新执行ssh-copy-id测试ssh root服务器IP能否免密登录push时报错“Repository not found”仓库地址写错或仓库是私有的检查_config.yml的repo地址确认仓库名称和用户名一致rsync同步后站点没有更新服务器目录权限不对执行chown -R www-data:www-data /var/www/hexoHTTPS证书到期后站点打不开Certbot自动续期定时器未启用执行systemctl status certbot.timer没有运行就手动启用域名访问出现GitHub Pages的404页面CNAME文件被覆盖在source下新建CNAME文件内容写域名重新生成部署部署时一直要求输入GitHub密码未使用Personal Access Token在GitHub Settings → Developer settings → Personal access tokens生成Token替代密码使用7.2 本地环境类故障故障现象可能原因解决方案hexo server提示端口被占用4000端口被其他程序占用执行hexo server -p 4001换端口或者先杀掉旧进程hexo generate时编码报错文章文件不是UTF-8编码用编辑器把文章另存为UTF-8格式不要用记事本另存为ANSI图片不显示相对路径写错文章内图片使用相对路径放到source/images目录下引用改了配置但生效不了Hexo缓存残留先hexo clean再hexo generate不要跳过clean7.3 一个容易忽视的坑文件权限导致的同步失灵rsync同步后站点文件的所有者通常是root用户。Nginx运行在www-data用户下时如果目录权限过于严格Nginx就无法读取文件。排查方法ls -l /var/www/hexo如果文件所有者是root且权限是600这种就需要调整权限chown -R www-data:www-data /var/www/hexo chmod -R 755 /var/www/hexo这个坑我在首次部署时踩过文件全部同步成功了但访问一直403。排查了半天才发现是权限问题——Nginx能看到目录但没权限读取里面的文件。7.4 网络解析和缓存类问题如果服务器部署正常但外部访问异常先检查DNS解析dig 你的域名检查解析结果是不是你的服务器IP。如果是再检查Nginx配置里是否监听了正确的端口以及防火墙有没有放行。还有一个容易被忽略的点浏览器缓存。改完配置后强制刷新页面的方式curl -I 你的域名看返回的HTTP状态码和响应头能判断页面到底是Nginx返回的、Nginx代理出去的还是被CDN缓存了。8. 进一步优化站点统计、图片压缩与自动化部署踩坑流程结束后这篇文章再来聊聊几个提升体验的优化项。这些不紧急但做完了会让博客更专业。8.1 站点统计和分析百度和谷歌统计等工具可以接入静态博客方式是复制一段JavaScript代码到主题中。我用的方案是直接在主题配置里填写统计ID不需要改动主题模板文件。具体操作看主题文档一般在_config.yml里配置baidu_site_id或google_analytics字段。集成后你可以在后台看到访客量、来源、访问页面等数据。8.2 图片压缩与懒加载Hexo博客写多了以后图片体积会成为影响加载速度的因素。我的习惯是上传前先压缩图片再使用懒加载插件。图片压缩工具有很多推荐用在线工具或者npm库进行批量压缩压缩率控制在50%以下基本看不出画质差异。懒加载插件能让图片进入浏览器视口时才加载首屏速度提升明显。8.3 自动部署的完整流程前面讲到双部署其实还可以继续自动化在服务器上配置一个定时任务定时拉取最新部署的文件。但是定时拉取有个问题如果本地没有执行hexo deploy服务器拉取的是旧文件。所以本质上还是要靠本地触发。重部署脚本的核心逻辑就是前面的hexo-publish脚本。如果你真的需要全自动流程那就是用GitHub Actionspush源文件到仓库后自动执行hexo generate和hexo deploy。这个方案能让你在手机上纯文本写文章、推送到仓库然后博客自动更新。我之前尝试过配置过程不难核心是写一个YAML工作流文件放在仓库的.github/workflows目录里。9. 写在最后的几个操作习惯建议整套流程跑通之后再分享几个我在实际使用中总结出来的操作习惯。这些不是“必须项”但长期坚持能省掉不少麻烦。第一点是写文章之前先预览。我习惯先在本地用hexo server预览确认排版、标签、图片都没问题后再执行部署。部署之前先预览的习惯能帮你避免把半成品发到线上。第二点是部署后主动检查站点状态。部署命令执行完毕不代表线上一定正常习惯性地访问一下站点首页确认状态再关终端能及时发现问题。第三点是给文章内容备份养成习惯。源文件和静态文件分别推到两个仓库等于给你的写作内容上了双保险。这个修炼对我来说很有用——有一次本地磁盘故障靠远程仓库完整恢复了所有文章。最后是重视服务器的安全维护。SSH登录建议改成密钥登录并禁用密码登录定期更新系统和软件包如果装了宝塔面板注意面板的安全入口。服务器安全是博客稳定运行的基础不要忽视。Hexo这座小桥走通之后你会发现写作本身变成了一件很轻快的事打开编辑器写Markdown一键部署完事。祝你顺利绕开我踩过的那些坑。