1. 为什么选择HexoGithub搭建个人博客十年前我第一次接触个人博客时用的还是WordPress。当时光是配置服务器环境就折腾了整整三天更别提后续的维护成本了。直到2015年发现Hexo这个静态博客框架配合Github Pages的免费托管服务我才真正找到了个人博客的完美解决方案。Hexo基于Node.js开发使用Markdown编写文章通过简单的命令就能生成静态网页。Github Pages则提供了免费的托管服务不仅支持自定义域名还能自动启用HTTPS加密。这个组合最大的优势在于完全免费除非你需要私有仓库无需服务器运维版本控制天然集成访问速度有保障Github的CDN覆盖全球我自己的技术博客示例域名blog.example.com已经稳定运行7年经历过多次主题更换和内容迁移这个技术栈始终保持着零宕机记录。下面我就详细拆解整个搭建过程包括几个主流主题的配置技巧和SEO优化经验。2. 环境准备与基础配置2.1 开发环境搭建首先需要安装Node.js环境建议使用LTS版本当前是18.x。Windows用户可以直接下载安装包Mac用户推荐通过Homebrew安装brew install node安装完成后检查版本我的环境示例node -v # v18.12.1 npm -v # 8.19.2接下来安装Hexo命令行工具npm install -g hexo-cli注意如果遇到权限问题可以在命令前加sudo或者按照官方文档配置npm的全局安装目录2.2 初始化博客项目创建一个新目录并初始化Hexo项目mkdir my-blog cd my-blog hexo init npm install目录结构说明. ├── _config.yml # 全局配置文件 ├── package.json # 依赖管理 ├── scaffolds/ # 模板文件 ├── source/ # 文章和静态资源 │ └── _posts/ # Markdown文章存放处 └── themes/ # 主题目录初始化的项目已经包含一个Hello World文章可以通过以下命令本地预览hexo server访问 http://localhost:4000 就能看到默认的Landscape主题效果。3. 主题定制与深度配置3.1 主题安装与切换Hexo有数百个开源主题我测试过二十余款后推荐这三个生产级选择Butterfly当前使用中安装npm install hexo-theme-butterfly特点功能全面支持暗黑模式文档完善NexT用户量最大安装npm install hexo-theme-next特点极简设计插件生态丰富Fluid适合技术文档安装npm install hexo-theme-fluid特点响应式布局搜索功能强大以Butterfly为例安装后需要在_config.yml中启用theme: butterfly3.2 主题配置实战技巧每个主题都有自己的配置文件通常位于themes/[theme-name]/_config.yml建议复制一份到博客根目录并重命名为_config.[theme-name].yml这样可以避免主题更新时配置丢失。几个关键配置项示例# 网站信息 title: 我的技术博客 subtitle: 记录开发中的点点滴滴 description: 前端开发 | Node.js | 性能优化 keywords: 技术博客,前端开发,JavaScript author: 你的名字 language: zh-CN # 菜单配置 menu: 首页: / || fas fa-home 归档: /archives/ || fas fa-archive 标签: /tags/ || fas fa-tags 关于: /about/ || fas fa-user # 代码高亮 highlight: enable: true line_number: true auto_detect: false tab_replace: wrap: true hljs: false避坑提示修改配置后务必重启Hexo服务hexo clean hexo server否则可能不生效4. 文章创作与管理4.1 Markdown写作规范Hexo支持标准的Markdown语法同时扩展了一些实用标签。新建文章命令hexo new 我的第一篇文章生成的Markdown文件头部包含Front-matter配置区--- title: 我的第一篇文章 date: 2023-07-20 14:00:00 tags: [Hexo, 教程] categories: 技术 cover: /images/post-cover.jpg # 文章封面图 ---我总结的最佳实践使用三级标题###作为内容分节代码块标注语言类型javascript图片存放在source/images目录每篇文章添加至少一个标签正文长度建议800-2000字4.2 高级内容管理技巧分页配置在全局配置中调整每页显示文章数index_generator: path: per_page: 10 order_by: -date草稿功能创建草稿后不会发布到生产环境hexo new draft 未完成文章 hexo publish 未完成文章 # 发布草稿文章加密安装插件实现密码访问npm install --save hexo-blog-encrypt然后在文章Front-matter中添加password: 123456 abstract: 这里是摘要 message: 请输入密码查看5. 部署到Github Pages5.1 仓库配置与自动化在Github创建名为[username].github.io的仓库username替换为你的账号安装部署插件npm install hexo-deployer-git --save修改全局配置deploy: type: git repo: https://github.com/[username]/[username].github.io.git branch: main message: Site updated: {{ now(YYYY-MM-DD HH:mm:ss) }}部署命令hexo clean hexo generate hexo deploy技巧可以在package.json中添加快捷命令scripts: { deploy: hexo clean hexo generate hexo deploy }然后通过npm run deploy一键部署5.2 自定义域名配置在域名服务商处添加CNAME记录记录类型CNAME 主机记录www 记录值[username].github.io在博客source目录创建CNAME文件无后缀内容为你的域名www.yourdomain.com在Github仓库Settings Pages中配置自定义域名6. 高级优化与SEO6.1 搜索引擎优化配置安装SEO插件npm install hexo-autonofollow hexo-generator-sitemap --save配置示例# 自动为外链添加nofollow nofollow: enable: true exclude: - yourdomain.com # 生成sitemap sitemap: path: sitemap.xml提交到Google Search Console验证域名所有权提交sitemap.xml配置索引优先级6.2 性能优化方案图片压缩安装插件自动压缩图片npm install hexo-image-min --saveCDN加速使用jsDelivr加速静态资源// 在主题配置中替换资源路径 cdn: enable: true jquery: https://cdn.jsdelivr.net/npm/jquery3.6.0/dist/jquery.min.js延迟加载Butterfly主题内置了lazyload功能lazyload: enable: true loading_img: /images/loading.gif7. 常见问题排查问题1部署后访问显示404检查仓库名称是否正确必须为[username].github.io确认部署到了main分支等待1-2分钟Github处理问题2样式丢失运行hexo clean清除缓存检查主题配置文件路径确保所有依赖已安装node_modules问题3自定义域名不生效确认CNAME文件已提交检查DNS解析是否生效可用dig工具测试Github仓库Settings中查看是否有错误提示问题4本地正常但线上异常比较本地与生产环境的Hexo和主题版本检查部署日志是否有报错尝试在另一台机器上测试我自己的博客在2020年迁移时遇到过front-matter解析异常最终发现是YAML格式中混用了Tab和空格。建议使用VS Code的YAML插件来校验语法。