企业官网建设流程全解析

1. 为什么我最终选择了 Hexo 而不是其他静态博客工具

1.1 从“写文章”这件事本身出发的选型逻辑

我最早写博客用的是在线平台，好处是注册就能写，坏处是数据不在自己手里，页面样式改不动，广告还时不时冒出来。后来陆续试过几种自建方案，最终稳定在 Hexo 上，原因其实很朴素：它把“写作”和“发布”这两件事拆得足够干净。

Hexo 是一个基于 Node.js 的静态博客生成器。你写的每一篇文章都是本地的一个 Markdown 文件，执行一条命令，它就把这些 Markdown 渲染成一套完整的 HTML 静态站点，然后你把生成出来的静态文件推到托管平台，博客就上线了。整个过程没有数据库、没有后端服务、没有运行时依赖，服务器只负责把 HTML 文件发出去。

这个特性带来的直接好处有三个。第一是快，静态页面没有数据库查询和模板实时渲染，打开速度几乎只取决于网络和文件大小。第二是稳，没有后端就没有后端漏洞，也不存在数据库连接失败、服务进程挂掉这类问题。第三是可迁移，你的全部资产就是一堆 Markdown 文件和一份配置文件，换电脑、换托管平台、甚至换生成器，成本都很低。

那为什么不是 Jekyll、Hugo 或者别的？我自己的判断标准是这样的：Jekyll 依赖 Ruby 环境，在部分系统上装依赖容易卡住；Hugo 用 Go 编写，构建速度确实快得离谱，但主题生态和中文资料相对 Hexo 少一些；Hexo 基于 Node.js，前端开发者基本人手一个 Node 环境，主题数量多，中文社区活跃，遇到问题搜得到答案。对于一个以“长期稳定写下去”为目标的个人博客来说，Hexo 的综合体验最均衡。

1.2 静态博客和动态博客的本质区别

很多人一开始会纠结“静态博客是不是功能很弱”。这里需要把概念理清楚。动态博客（比如传统的 WordPress）是每次有人访问，服务器现场查数据库、拼页面再返回；静态博客是提前把所有页面生成好，访问时直接返回现成文件。

打个比方，动态博客像餐厅现点现做，灵活但高峰期慢；静态博客像提前备好的便当，拿出来就能吃，速度极快。代价是评论、搜索、访问统计这些“需要实时交互”的功能，静态博客本身不提供，得靠第三方服务或者客户端脚本来补。

对个人博客来说，这个取舍非常划算。绝大多数个人博客的核心诉求就是“把文章稳定地展示出来”，评论和统计属于锦上添花。而且这些功能现在都有成熟的第三方方案，挂一段脚本就能用，完全不影响静态站点的整体架构。

1.3 一键部署到底“一键”在哪里

标题里说的“在 GitHub 上一键部署”，本质是利用 GitHub 提供的静态页面托管能力，配合自动化构建流程，把“本地生成 + 手动上传”这两步合并成“推送代码后自动完成”。

传统流程是：本地写完文章，执行生成命令，得到 public 目录，再用工具把 public 目录的内容推送到托管分支。这个流程每次都要重复，容易忘、容易出错。而自动化流程是：你把源码推送到仓库的某个分支，托管平台检测到推送后，自动帮你执行生成命令，再把结果发布出去。你只需要做一件事——推送源码。

这就是“一键”的真正含义：把重复劳动交给自动化，人只负责创作。下面我会把整套流程从环境准备到自动化部署完整拆一遍，包括我踩过的坑和参数选择的理由。

2. 环境准备与 Hexo 初始化实操

2.1 Node.js 与 Git 的安装要点

Hexo 运行在 Node.js 之上，所以第一步是装 Node。版本选择上，我建议用当前主流的 LTS（长期支持）版本，不要追最新的实验版。原因很简单：Hexo 及其插件对 Node 版本有一定兼容范围，太新的版本偶尔会出现依赖编译失败的问题，而 LTS 版本经过大量用户验证，最稳。

安装方式上，Windows 用户直接去 Node.js 官网下载安装包，一路下一步即可，安装时会自动带上包管理工具 npm。macOS 用户如果装了包管理器，一条命令就能搞定；没装的话也可以用官网安装包。安装完成后，打开终端验证：

node -v npm -v

两条命令都能输出版本号，说明环境正常。如果提示“命令未找到”，多半是安装时没勾选“添加到系统路径”，重装一次并勾选即可。

Git 同样需要安装，因为后面要把代码推送到远程仓库。装完后配置一下身份信息，这两条配置会记录在每次提交里：

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

注意：这里的邮箱建议和你后面注册的代码托管平台账号邮箱保持一致，否则提交记录可能无法正确归属到你名下。

2.2 安装 Hexo 命令行工具

环境就绪后，全局安装 Hexo 的命令行工具：

npm install -g hexo-cli

装完后执行hexo -v，能看到版本信息就说明成功了。这里有个常见坑：如果你用的是 macOS 或 Linux，全局安装可能因为权限问题报错。不要直接用管理员权限去装，那样容易把全局目录的权限搞乱。正确做法是配置 npm 的全局安装目录到用户目录下，或者使用 Node 版本管理工具来管理环境。Windows 用户一般不会遇到这个问题。

2.3 初始化博客项目与目录结构解读

找一个你习惯放代码的目录，执行初始化：

hexo init my-blog cd my-blog npm install

第一条命令会创建一个名为 my-blog 的文件夹并生成基础骨架，第二条命令安装项目依赖。初始化完成后，你会看到这样一套目录结构，理解每个目录的作用非常关键：

我特别想强调source/_posts和_config.yml这两个位置。前者是你的内容资产，后者是你的站点行为控制中心。把这两个地方摸熟，Hexo 就算入门了。

2.4 本地预览：先跑起来再谈美化

初始化完成后，先别急着改配置，直接启动本地服务看看默认效果：

hexo server

终端会提示服务运行在本地某个端口（默认 4000）。浏览器打开对应地址，能看到一篇默认的 Hello World 文章，说明整条链路是通的。这个本地服务支持热更新，你改了文章或配置，刷新页面就能看到变化，不用反复重启。

实操心得：本地预览时如果页面样式错乱，先检查是不是浏览器缓存。强制刷新（清缓存刷新）往往能解决大部分“看起来没生效”的问题。

3. 站点配置与主题定制的核心细节

3.1 主配置文件里必须改的几个参数

打开根目录的_config.yml，参数很多，但真正影响站点基本面貌的就那么几个。我按重要性排一下：

title: 我的博客 # 站点标题，显示在浏览器标签和页头 subtitle: 记录与思考 # 副标题 description: 一个普通人的技术笔记 # 站点描述，影响搜索引擎摘要 author: 你的名字 # 作者名 language: zh-CN # 语言，中文站点务必改成这个 timezone: Asia/Shanghai # 时区，影响文章时间显示

language这一项特别容易被忽略。默认是英文，如果不改，主题里的一些内置文案（比如“”“上一篇”）会显示英文，中文站点看起来就很别扭。改成zh-CN后，支持中文的主题会自动切换文案。

timezone也建议显式设置。如果不设，生成的时间可能按服务器时区走，导致文章发布时间和你实际写的时间对不上，尤其是部署到云端自动构建时更明显。

3.2 主题选型与安装方式对比

Hexo 的主题生态是它的一大优势。选主题我一般看三点：更新是否活跃、文档是否完整、移动端适配是否到位。一个长期不更新的主题，遇到 Hexo 版本升级很容易出兼容问题。

安装主题有两种主流方式。第一种是直接把主题文件下载到themes目录，优点是简单直接，缺点是主题更新时你得手动替换。第二种是用 Git 子模块的方式引入，优点是主题可以独立更新，缺点是操作稍复杂，对新手不够友好。

我个人的建议是：新手先用直接下载的方式，把博客跑起来、写起来最重要。等你对整套流程熟悉了，再考虑用子模块管理主题。安装完主题后，在_config.yml里把theme字段改成主题文件夹的名字，这一步千万别写错，否则主题不生效。

3.3 主题配置的通用套路

每个主题都有自己的配置文件，通常在主题目录下的_config.yml。虽然各主题参数不同，但套路是相通的，一般包含这几类：

• 导航菜单：配置顶部导航栏显示哪些页面，比如首页、归档、关于。
• 社交链接：配置你的各个平台主页地址，显示为图标。
• 样式开关：是否开启暗色模式、代码高亮风格、动画效果等。
• 第三方集成：评论系统、访问统计、搜索功能的开关和密钥。

改主题配置时，我强烈建议改一项、预览一次。一次性改一大堆再刷新，出了问题根本不知道是哪一项引起的。这个习惯能帮你省下大量排查时间。

3.4 新建文章与 Front-matter 写法

写文章用这条命令：

hexo new "文章标题"

它会在source/_posts下生成一个 Markdown 文件，开头有一段被三条横线包裹的配置区，叫 Front-matter：

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

这里有几个细节值得说。date如果不写，Hexo 会用当前时间，但如果你在云端自动构建，时间可能不准，所以重要文章建议手动写死。tags和categories的区别是：分类是一对多的层级关系，标签是多对多的自由标记。我的习惯是分类少而稳定（比如“技术”“生活”），标签多而灵活（比如具体的技术名词）。

注意：Front-matter 里的冒号后面必须有一个空格，这是 YAML 语法要求。漏了空格会导致解析失败，文章可能直接不显示。

4. 从本地生成到远程仓库的完整部署链路

4.1 生成静态文件与本地验证

文章写完，执行生成命令：

hexo generate

简写是hexo g。这条命令会把source下的 Markdown 和资源渲染成完整的 HTML，输出到public目录。生成完成后，我建议先本地预览一遍再部署：

hexo server

重点检查三件事：文章能不能正常打开、图片能不能正常显示、导航链接有没有失效。这三项没问题，基本就可以部署了。很多人跳过本地验证直接推，结果线上出问题再回头查，效率反而低。

4.2 创建远程仓库的命名规则

在代码托管平台创建一个新仓库。这里有个极其关键的命名规则：如果你打算用平台提供的默认域名访问博客，仓库名通常需要遵循特定格式（一般是“用户名.github.io”这种形式）。如果仓库名不符合规则，默认域名就访问不到，只能走自定义域名。

创建仓库时，建议设为公开仓库。虽然私有仓库也能配合某些付费功能实现托管，但对个人博客来说，公开仓库最简单、最省事，而且源码公开本身也不是什么坏事。

4.3 部署插件的安装与配置

Hexo 本身不直接负责推送，需要装一个部署插件：

npm install hexo-deployer-git --save

然后在_config.yml里配置部署信息：

deploy: type: git repo: 你的仓库地址 branch: 部署分支名

这里的branch需要重点说明。如果你用的是“源码和生成结果分开管理”的方案，源码放一个分支，生成结果放另一个分支（比如 main 或 gh-pages），那么这里填的就是生成结果所在的分支。具体填哪个，取决于你在托管平台里把哪个分支设置为发布源。

配置完成后，执行三连命令：

hexo clean hexo generate hexo deploy

clean是清掉缓存和旧的 public 目录，避免残留文件干扰；generate重新生成；deploy推送到远程。这三步合起来可以简写为hexo clean && hexo g && hexo d。

4.4 自动化部署：把三连命令交给平台执行

手动执行三连命令虽然简单，但每次都要敲一遍，时间久了会烦。更优雅的方案是配置自动化：你只推送源码，平台自动帮你生成并发布。

实现思路是这样的：在仓库里配置一个自动化流程文件，告诉平台“当我推送源码时，帮我安装依赖、执行生成命令、把结果发布出去”。这个流程文件通常放在特定目录下，用平台约定的语法编写。

一个典型的流程包含这几步：检出代码、安装 Node 环境、安装依赖、执行生成、发布产物。每一步都有对应的配置项。这里最容易出问题的是依赖安装和权限配置。依赖安装要确保用的是项目锁定的版本，权限配置要确保自动化流程有权限把结果推送到发布分支。

实操心得：自动化流程第一次配置时，建议先在一个测试仓库里跑通，确认无误再迁移到正式博客仓库。直接在主仓库调试，一旦流程写错，可能把发布分支搞乱。

4.5 自定义域名的绑定要点

如果你有自己的域名，绑定流程分两步。第一步是在仓库的设置里填写自定义域名，平台会生成一个验证记录。第二步是在你的域名解析服务商那里，添加一条指向托管平台的记录。

这里有个细节：域名解析生效需要时间，短则几分钟，长则几小时。刚配置完访问不了是正常的，别急着反复改配置。另外，绑定自定义域名后，建议开启强制加密访问，避免出现部分资源加载失败的问题。

5. 常见问题排查与避坑经验实录

5.1 部署后页面 404 或样式丢失

这是新手遇到最多的问题。排查顺序我总结成一张表：

样式丢失这个问题，十有八九是根路径配置不对。如果你的博客部署在子路径下（比如仓库名作为路径），需要在配置里把根路径改成对应的子路径，否则所有资源都会去根目录找，自然找不到。

5.2 自动化流程执行失败的典型原因

自动化流程跑失败，终端日志是最好的老师。我遇到过的几类典型错误：

第一类是依赖安装失败，通常是 Node 版本和依赖不兼容。解决办法是在流程配置里显式指定 Node 版本，和本地保持一致。

第二类是权限不足，表现为推送产物时被拒绝。这需要在仓库设置里给自动化流程授予写权限，不同平台的叫法不同，但本质都是“允许自动化流程修改仓库内容”。

第三类是缓存导致的诡异问题。有时候本地能生成，云端却失败，清理缓存后重跑往往就好了。所以我在流程里一般会加上清理缓存的步骤。

5.3 文章时间显示不对

前面提过时区问题，这里再展开说。如果你在配置里设了时区，但文章时间还是不对，检查两个地方：一是 Front-matter 里的date是否手动写死，二是自动化流程运行环境的时区。最稳妥的做法是文章时间手动写，不依赖系统时间。

5.4 主题更新后样式错乱

主题更新后样式错乱，多半是主题配置文件和你的自定义修改冲突了。我的经验是：改主题前先备份主题配置文件。更新主题后，把备份的配置和新的默认配置对比，把自定义项重新填回去。直接覆盖更新，很容易丢掉你之前调好的设置。

5.5 我踩过的三个真实坑

第一个坑是仓库名写错。我一开始没注意命名规则，随便起了个名字，结果默认域名死活访问不了，折腾半天才发现是仓库名的问题。这个坑的教训是：动手前先把平台的命名规则看清楚。

第二个坑是部署分支和发布分支搞混。源码推上去了，但发布源设置的是另一个分支，导致线上一直是旧内容。后来我把两个分支的职责在配置里写清楚，再也没混过。

第三个坑是图片路径用绝对路径。本地预览正常，线上全挂。原因是绝对路径指向了本地文件系统。改成相对路径后问题解决。这个坑让我养成了一个习惯：所有资源引用一律用相对路径。

6. 长期维护与内容运营的实用建议

6.1 备份策略：源码才是核心资产

静态博客最宝贵的不是生成出来的 HTML，而是你的 Markdown 源码和配置。我的做法是源码仓库保持更新，每次写完文章就推送一次。这样即使本地电脑出问题，云端还有完整备份。生成结果不需要备份，因为它随时可以从源码重新生成。

6.2 写作流程的固化

写久了你会发现，效率的关键在于流程固定。我的流程是：新建文章、写正文、本地预览、推送、等自动化发布。每一步都有固定命令，形成肌肉记忆后，从写到发布也就几分钟的事。不要每次都临时想“我该先干嘛”，那会消耗大量精力。

6.3 图片管理的两种思路

图片放哪，有两种常见做法。一种是放在文章同级目录下建一个同名文件夹，引用时用相对路径，好处是文章和图片绑定在一起，迁移方便。另一种是统一放在一个资源目录里，好处是管理集中。我个人倾向第一种，因为文章多了以后，按文章归档图片更清晰。

6.4 什么时候该考虑换方案

Hexo 不是万能的。如果你的文章数量到了几千篇，生成速度会明显变慢，这时候可以考虑构建更快的生成器。如果你需要复杂的交互功能，静态博客的补丁方案会越来越吃力，可能需要考虑带后端的方案。但对绝大多数个人博客来说，Hexo 的适用范围足够宽，不用过早担心这些问题。

我在实际使用中最大的体会是：工具只是工具，真正让博客有价值的，是持续写下去这件事本身。Hexo 加自动化部署这套组合，最大的意义就是把你从技术细节里解放出来，让你能把精力放在内容上。配置一次，之后就是纯粹的写作和推送，这种顺畅感才是它最值得推荐的地方。