1. 为什么我最终选择了Hexo这套静态博客方案折腾个人博客这件事我前前后后换过不下五种方案。最早用WordPress光是服务器续费和数据库维护就够头疼后来试过一些在线笔记直接发布自由度又太低样式改不动、域名绑不了。直到我把Hexo、PicGo和代码托管平台的Pages服务串起来用才算真正找到了一个能长期坚持下去的组合。这套方案的核心逻辑其实很简单Hexo负责把Markdown文件编译成静态网页PicGo负责把图片自动上传到图床并回填链接代码托管平台的Pages服务负责免费托管这些静态文件。三者各司其职你只需要专注写内容就行。整个过程零服务器成本零数据库维护对个人博客来说完全够用。这篇文章适合谁看如果你满足下面任意一条那接下来的内容应该能帮你省下不少摸索时间想搭一个完全属于自己的博客但不想买服务器、不想备案平时习惯用Markdown写作希望发布流程越简单越好写技术文章需要大量配图但手动传图、复制链接太折磨人之前尝试过类似方案但卡在某个环节比如图片加载不出来、部署后样式丢失我会从整体设计思路讲起然后拆解每个环节的具体操作最后把我踩过的坑和排查方法一并整理出来。你跟着走一遍基本能搭出一个稳定可用的博客加图床体系。2. 整体架构设计与方案选型思路2.1 三个组件各自扮演什么角色先把这套方案的骨架说清楚不然后面操作容易知其然不知其所以然。Hexo是一个基于Node.js的静态博客框架。它的工作方式是你写Markdown它通过主题模板把Markdown渲染成HTML最终生成一个public文件夹里面全是静态文件。静态文件的好处是不需要后端程序实时处理请求访问速度快也不存在数据库被拖垮的问题。PicGo是一个图片上传工具支持多种图床服务。它的核心价值在于自动化你在编辑器里粘贴一张截图PicGo自动上传到图床然后把Markdown格式的图片链接直接插入到光标位置。没有它的话你得手动打开图床网站、上传、复制链接、回到编辑器粘贴一篇文章十张图就是十次重复劳动。代码托管平台的Pages服务负责托管Hexo生成的静态文件。你把public文件夹推送到仓库平台自动帮你发布成一个可访问的网站。这里我同时用了两个平台原因后面会讲。2.2 为什么不用动态博客有人可能会问现在服务器也不贵为什么非要折腾静态博客。我的实际体验是动态博客的隐性成本远不止服务器费用。数据库需要定期备份程序需要更新补丁插件冲突要排查访问量稍微上来一点还要考虑缓存和CDN。静态博客把这些全部省掉了生成一次HTML谁访问都是读同一份文件稳定得让人放心。另一个关键因素是版本管理。Hexo的源文件就是Markdown加配置文件全部放在代码仓库里每次改动都有记录换电脑只需要克隆仓库重新安装依赖就行。动态博客的数据库迁移起来就麻烦多了。2.3 双平台部署的考量标题里写了GitHub和Gitee两个平台这不是随便加的。实际使用中两个平台各有优劣我建议同时配置互为备份。对比维度GitHub PagesGitee Pages访问速度国内访问一般国内访问较快自定义域名支持支持自动部署推送即触发需手动更新或配置稳定性高较高免费额度充足充足我的做法是主站部署在Gitee保证国内访问速度同时推一份到GitHub作为备份和海外访问入口。两边内容完全一致通过同一个Hexo源仓库生成。2.4 图床方案的选择逻辑图床这块我试过几种方案最终选择了代码托管平台的仓库作为图床。原因有三点第一不需要额外注册图床服务用现有的仓库就行第二图片和博客内容在同一个平台体系内管理起来方便第三免费额度对个人博客来说绰绰有余。具体做法是在仓库里建一个专门存放图片的分支或文件夹通过PicGo上传图片后拿到原始文件链接直接在Markdown里引用。这里需要注意链接的格式不同平台返回的链接形式不一样后面实操部分会详细说明。3. 环境准备与基础工具安装3.1 Node.js和Git的安装要点Hexo依赖Node.js运行所以第一步是装Node.js。我建议直接去官网下载LTS版本不要追求最新版。LTS版本经过充分测试兼容性最好。安装过程中有一个选项需要注意是否自动安装必要的编译工具。Windows环境下建议勾选否则后续安装某些依赖时可能报错。安装完成后打开终端验证node -v npm -v两条命令都能输出版本号就说明安装成功。这里有个小细节npm的版本最好在6以上太老的版本安装Hexo时可能出问题。如果npm版本偏低可以用npm install -g npm升级。Git的安装相对简单一路默认选项即可。装完后配置一下用户名和邮箱这是提交代码时记录身份用的git config --global user.name 你的用户名 git config --global user.email 你的邮箱注意这里的用户名和邮箱建议和后面代码托管平台注册的信息保持一致否则提交记录里的作者信息会显示异常。3.2 Hexo的安装与初始化Node.js和Git就绪后安装Hexo的命令行工具npm install -g hexo-cli如果下载速度慢可以临时切换npm镜像源npm config set registry https://registry.npmmirror.com安装完成后找一个合适的目录初始化博客hexo init my-blog cd my-blog npm installhexo init会生成一套默认的博客骨架包括配置文件、源文件目录、主题目录等。npm install负责安装依赖包。这两步完成后执行hexo server就能在本地预览默认博客了浏览器访问http://localhost:4000即可。3.3 PicGo的安装与基础配置PicGo有图形界面版本和命令行版本我推荐用图形界面版配置直观日常使用也方便。安装完成后打开先不急着配置图床把基础设置过一遍。在PicGo的设置里有几个选项建议调整快捷键设置默认的截图上传快捷键可能和其他软件冲突建议改成自己顺手的组合上传后自动复制链接勾选这个选项上传完直接就能粘贴链接格式选择Markdown格式这样粘贴到编辑器里直接就是![](链接)的形式PicGo本身不存储图片它只是一个上传工具真正存图片的是你配置的图床。所以接下来要配置图床这部分放到下一章和图床搭建一起讲。4. 图床搭建与PicGo深度配置4.1 用代码仓库搭建图床的完整流程图床的本质就是一个能通过URL直接访问图片文件的存储空间。代码托管平台的仓库天然满足这个条件你把图片推送到仓库平台提供原始文件的访问链接这个链接就是图片的URL。具体操作步骤如下在代码托管平台新建一个仓库命名为images或pic-bed之类的名字设为公开仓库在仓库里创建一个分支比如叫img或者直接在main分支下建一个images文件夹生成一个访问令牌这是PicGo上传图片时的凭证访问令牌的生成位置在账户设置的开发者选项里。生成时需要注意权限范围只勾选仓库读写权限即可不要勾选全部权限。令牌生成后只显示一次务必立即复制保存。4.2 PicGo配置图床的参数详解打开PicGo的图床设置选择对应的平台填入以下信息配置项说明示例仓库名用户名/仓库名yourname/images分支名存放图片的分支main令牌刚才生成的访问令牌一串字符存储路径图片存放的子目录blog/自定义域名可选加速访问留空或填CDN域名存储路径这个选项很实用可以按年份月份自动分目录比如设置成blog/2024/图片多了也不会乱。自定义域名如果暂时没有留空即可PicGo会用平台默认的原始文件链接。配置完成后点“设为默认图床”然后在PicGo的上传区拖一张图片测试。上传成功后PicGo会自动把Markdown链接复制到剪贴板粘贴到任何编辑器里都能直接用。4.3 图片链接格式的坑与处理这里有一个很容易踩的坑不同平台返回的图片链接格式不一样。有的返回的是仓库页面链接有的是原始文件链接还有的是带参数的链接。你需要的是能直接渲染出图片的原始文件链接。判断方法很简单把链接粘贴到浏览器地址栏如果直接显示图片而不是下载或者跳转到页面那就是对的。如果不对需要在PicGo的配置里调整链接格式或者在自定义域名里填入正确的原始文件地址前缀。提示Gitee的原始文件链接格式和GitHub略有不同配置时注意区分。如果图片显示不出来九成是链接格式的问题优先排查这里。4.4 批量上传与图片管理技巧PicGo支持拖拽多张图片批量上传上传完成后所有链接会按顺序排列。写文章时如果一次性截了很多图可以全部拖进去然后按顺序粘贴。图片管理方面我建议在仓库里按博客文章分文件夹存放。比如写一篇关于Docker的文章就在blog/docker/目录下存这篇的所有配图。这样以后要清理或者替换图片时能快速定位。另外PicGo有一个“上传前重命名”的功能建议开启。默认的图片文件名是一串随机字符开启重命名后可以按时间戳命名避免文件名冲突也方便追溯上传时间。5. Hexo主题配置与写作工作流5.1 主题选择与安装Hexo默认主题比较简陋实际使用建议换一个功能完善的主题。选择主题时重点看三个维度是否支持响应式布局、是否内置常用功能如目录、搜索、评论、文档是否齐全。安装主题的通用步骤是进入博客目录克隆主题仓库到themes文件夹cd my-blog git clone 主题仓库地址 themes/主题名然后在博客根目录的_config.yml里把theme字段改成主题名。改完后执行hexo clean清除缓存再hexo server预览效果。主题的个性化配置通常在主题目录下的_config.yml里可以配置导航菜单、社交链接、配色方案等。建议先把主题文档通读一遍了解每个配置项的作用再动手改。5.2 写作流程与Front-matter规范Hexo的文章放在source/_posts目录下每篇文章是一个Markdown文件。文件开头有一段Front-matter用来声明文章的元信息--- title: 文章标题 date: 2024-01-01 10:00:00 tags: - 标签1 - 标签2 categories: - 分类名 ---Front-matter的字段根据主题不同可能有所扩展比如有的主题支持cover字段指定封面图有的支持description字段做摘要。写文章前先确认主题支持哪些字段按需填写。新建文章的快捷命令是hexo new 文章标题Hexo会自动在_posts目录下生成一个带基础Front-matter的Markdown文件。我习惯直接用编辑器手动创建文件这样对文件名的控制更灵活。5.3 本地预览与实时调试写作过程中随时可以本地预览。执行hexo server启动本地服务浏览器打开http://localhost:4000就能看到效果。Hexo默认会监听文件变化修改Markdown后刷新浏览器即可看到更新不需要重启服务。如果修改了主题配置文件或者安装了新插件可能需要hexo clean清除缓存后再重新生成。这个命令相当于把之前编译的结果全部删掉重新来一遍遇到样式异常或者内容不更新时先执行它准没错。提示本地预览时图片链接如果是图床的在线链接需要联网才能显示。如果网络环境不稳定可以先把图片下载到本地用相对路径引用发布前再替换成在线链接。5.4 文章摘要与SEO基础设置Hexo默认会把文章全文输出到首页文章多了以后首页会很长。可以在Front-matter里加!-- more --标记标记之前的内容会作为摘要显示在首页之后的内容需要点击“阅读全文”才能看到。SEO方面主题通常内置了基础优化比如自动生成sitemap、设置meta标签等。你可以在博客根目录的_config.yml里配置站点标题、关键词、描述等信息这些会体现在生成的HTML里。另外文章链接的格式也建议在配置文件里调整默认是年月日加标题可以改成更简洁的格式。6. 部署上线与双平台同步策略6.1 部署前的检查清单在部署之前有几项检查建议过一遍避免上线后发现问题再回头改博客根目录_config.yml里的url字段是否填了最终访问地址主题配置文件里的导航链接、社交链接是否都指向正确文章里的图片链接是否都能正常访问本地预览时是否有样式错乱或功能异常这些检查花不了几分钟但能省掉部署后反复修改重新推送的麻烦。6.2 部署到代码托管平台Pages的完整流程部署的本质是把Hexo生成的public文件夹推送到代码仓库的特定分支。有两种方式一种是手动推送一种是安装部署插件自动推送。手动推送的流程是hexo generate cd public git init git add . git commit -m update git push 仓库地址 分支名自动推送需要安装hexo-deployer-git插件然后在_config.yml里配置部署参数deploy: type: git repo: 仓库地址 branch: 分支名配置好后执行hexo deployHexo会自动生成并推送。我推荐用自动方式省事且不容易出错。6.3 双平台同步的配置方法同时部署到两个平台只需要在deploy配置里写两个repodeploy: - type: git repo: 平台1仓库地址 branch: main - type: git repo: 平台2仓库地址 branch: main执行一次hexo deployHexo会依次推送到两个仓库。两个平台的Pages服务各自独立发布互不影响。需要注意的是两个平台的Pages服务触发机制不同。有的平台推送后自动发布有的需要手动在网页端点击更新。首次配置时建议分别确认一下发布状态确保两边都能正常访问。6.4 自定义域名与HTTPS配置如果不想用平台默认的二级域名可以绑定自己的域名。流程是在域名服务商处添加一条CNAME记录指向平台的Pages地址然后在平台的仓库设置里填入自定义域名。HTTPS方面主流平台都支持自动签发证书绑定域名后等待几分钟即可生效。如果平台不支持自动HTTPS可以通过CDN服务来间接实现把域名解析到CDNCDN回源到Pages地址由CDN提供HTTPS证书。注意绑定自定义域名后博客配置文件里的url字段要同步改成新域名否则生成的链接还是旧地址可能导致样式和图片加载异常。7. 常见问题排查与避坑经验实录7.1 图片上传失败排查表现象可能原因解决方法上传报401错误令牌无效或过期重新生成令牌并更新PicGo配置上传报404错误仓库名或分支名填错核对仓库名格式为用户名/仓库名上传成功但链接打不开链接格式不对检查是否为原始文件链接图片显示但很慢图床服务器响应慢考虑使用CDN加速或换平台部分图片上传失败单张图片过大压缩图片后重新上传7.2 部署后样式丢失的排查思路部署后样式丢失是最常见的问题之一表现是页面能打开但完全没有样式或者图片全部裂开。根本原因通常是路径问题。Hexo生成的静态文件里资源引用路径有两种模式绝对路径和相对路径。如果配置文件里的url和root字段设置不对生成的路径就会错位。排查方法是打开浏览器开发者工具看Network面板里哪些资源加载失败根据失败资源的URL反推路径配置哪里出了问题。另一个常见原因是仓库的Pages服务配置了错误的发布目录。比如public文件夹推送到了仓库根目录但Pages服务配置的是从docs目录发布那自然找不到文件。检查仓库的Pages设置确保发布目录和实际文件位置一致。7.3 本地正常线上异常的定位方法有时候本地预览一切正常部署后却出问题。这种“本地正常线上异常”的情况排查起来有个基本思路先确认线上文件是否和本地一致。具体做法是打开线上页面查看源代码对比本地生成的HTML文件。如果HTML内容一致但表现不同那问题出在资源加载上如果HTML内容就不一致那说明部署过程有问题可能是推送不完整或者平台缓存了旧版本。平台缓存这个问题很隐蔽。有的平台Pages服务会缓存静态文件更新后短时间内访问的还是旧版本。遇到这种情况可以在推送时加一个无意义的查询参数强制刷新或者等待缓存过期。7.4 写作与发布环节的独家避坑技巧分享几个我在实际使用中总结的小技巧都是踩过坑之后才明白的。第一图片文件名不要用中文。虽然理论上支持但实际使用中中文文件名在URL编码后容易出问题有的平台直接不支持。统一用英文加数字命名省心。第二文章发布前先在本地完整预览一遍。特别是图片和代码块这两样最容易出问题。图片看是否都能加载代码块看语言标注是否正确、缩进是否保留。第三部署命令不要频繁执行。有的平台对推送频率有限制短时间内多次推送可能触发限制。建议本地确认无误后再执行部署一次到位。第四定期备份源文件。Hexo的源文件Markdown、配置文件、主题配置才是核心资产生成的public文件夹随时可以重新生成。源文件建议单独建一个私有仓库管理和部署仓库分开。第五图床仓库不要放敏感内容。公开仓库意味着任何人都能访问图片内容要注意合规。如果图片涉及隐私建议用支持私有仓库的图床方案。7.5 性能优化与访问加速建议博客上线后如果访问速度不理想可以从几个方向优化。图片是最影响加载速度的因素。上传前用工具压缩一下通常能减少一半以上的体积。PicGo有压缩插件可以在上传时自动压缩。主题层面检查是否有不必要的JavaScript和CSS文件。有的主题默认加载了很多用不到的功能模块可以在主题配置里关掉。如果条件允许给博客套一层CDN。CDN会把静态文件缓存到离用户最近的节点访问速度提升明显。大部分CDN服务对静态文件都有免费额度个人博客完全够用。最后再分享一个我用了很久的写作节奏平时想到什么就随手记在草稿文件里攒够一篇的量再整理成正式文章。这样不会因为“要写一篇完整的文章”而拖延写作压力小很多。Hexo的草稿功能可以配合这个习惯用hexo new draft 标题创建草稿写完后用hexo publish发布为正式文章。