企业官网建设流程全解析

1. 为什么是 Hexo + GitHub Pages，而不是其他博客方案

1.1 静态博客到底解决了什么问题

很多人一听“自己搭博客”就觉得门槛很高：域名、服务器、数据库、运维，每一项对普通人都像一座山。我一开始也是这么想的，直到朋友推荐我用 Hexo 搭配 GitHub 的 Pages 服务，才意识到个人博客完全可以零成本、零维护地跑起来。Hexo 做的事情其实很单纯：你写 Markdown，它渲染出一整套 HTML 静态页面；GitHub Pages 做的事情更单纯：你推一个仓库上去，它把里面的网页托管出来。两条链路加起来，就是一条“写文章给世界看”的最短路径。我会把这条路径完整走一遍给你看，从环境准备讲到部署上线，再讲到日常更新和踩坑排查，想搭博客又不太熟悉命令行的朋友可以直接照着做。

先把“静态”这两个字说透。博客的核心需求其实是展示文字、图片和少量交互，这些东西本质上不需要数据库参与。传统动态博客每一次访问都由服务器现场拼装页面，背后牵扯到 PHP 运行环境、数据库读写、缓存策略、安全补丁、备份方案。对个人作者来说，这些功能绝大多数时间用不上，反而变成持续的负担。静态博客的思想是“提前把活干完”：你在本地把文章渲染成纯 HTML 文件，服务器只负责把现成的文件发给访问者，省掉了所有动态计算的环节，所以访问快、吃资源少、被攻击面也小得多。

1.2 Hexo 在静态生成器里为什么适合新手

市面上的静态博客生成器不少，除了 Hexo，还有 Jekyll、Hugo 这些选项。Jekyll 是 GitHub 原生支持的方案，但它依赖 Ruby 环境，对 Windows 用户尤其不友好；Hugo 以极快的生成速度著称，但主题系统的概念层级比较多，上手时容易一头雾水。我最终选择 Hexo，原因很实际：基于 Node.js，生态完整，中文资料极多，遇到问题几乎都能搜到现成答案；主题市场也足够丰富，极简风、学术风、卡片风都有成熟选择，换个主题往往只是改一行配置的事。

另外一个容易被忽略的点是生成速度与文章规模的关系。个人博客文章量一般不会太大，几百篇以内 Hexo 的生成速度都相当可观，没必要为了更快去折腾其他框架。如果你写博客的内容以技术笔记和生活记录为主，Hexo 完全够用，而且它的写法非常一致：文章就是 Markdown 文件，装在哪台电脑上都能打开，永远不用担心某个编辑器升级后格式错乱。

1.3 GitHub Pages 作为托管的边界条件

GitHub Pages 是 GitHub 提供的免费静态网页托管服务，和博客生成器正好是一对。它有几个鲜明的特点：只接受静态文件、绑定一个仓库后自动发布、默认自带 HTTPS、有很宽松的软性限制（单仓库 1GB 以内、月流量百 GB 级别），个人博客远不会触及红线。更关键的是，它支持自定义域名，以后想把自己注册的域名接过来，只需要在仓库设置里配置一下 CNAME 记录，不需要搬数据。

我做选择时心里有一张对比表，现在也分享给你：

用过平台博客的人大概都有类似的体会：排版受编辑器限制、账号规则跟着平台变、内容数据不完全由自己掌控。静态博客把所有内容变成普通文件，推到自己的仓库里，“内容真正属于自己”这句话才算落到实处。

2. 搭建前的三件套：Node.js、Git 与终端基础

2.1 Node.js 是 Hexo 的运行底座

Hexo 本身是跑在 Node.js 上的命令行工具，安装它的前提是先装 Node.js。这里有个简单的原则：去官网下载 LTS（长期支持）版本就行，不要追最新版。原因很务实，Hexo 生态里的各种插件依赖的是 Node 的稳定 API，LTS 版本表现最一致。安装完成后，打开终端验证一下：

node -v npm -v

能分别输出版本号，说明环境没问题。顺带解释一下 npm：它是 Node.js 自带的包管理器，Hexo 的框架本体和后续所有插件都以 npm 包的形式存在。后面你会经常和 npm 打交道，不需要深入了解原理，只要知道“装工具用 npm install，装到全局加 -g”就够了。

2.2 Git 的身份配置决定了提交归属

Git 是第二件必备工具，它的职责是把本地生成的页面提交并推送到 GitHub。安装 Git 之后，第一件事不是急着干活，而是配置你的身份信息：

git config --global user.name "你的GitHub用户名" git config --global user.email "你注册用的邮箱"

这两行配置会写进每一次提交记录里，GitHub 靠它把提交关联到你的账号。如果不配置，提交记录会显示成一个陌生的 ID，后面排查问题、管理历史都会很别扭。需要提醒的是，--global表示这台电脑上的所有仓库都默认使用这套身份，如果电脑是多人共用的，记得改成只对当前仓库配置。

2.3 终端基础别焦虑：只需要几条命令

“命令行”这三个字劝退过不少人，但搭建博客真正用得上的命令一只手数得过来：pwd查看当前所在目录，ls列出目录里的文件，cd切换目录，mkdir新建目录。Windows 用户可以用 PowerShell 或 Git Bash，macOS 直接用自带的终端。初学者最常犯的错误是在错误的目录下执行命令，所以建议你养成一个习惯：每次打开终端，先敲一下pwd确认自己在哪，再动手。

注意：以后所有hexo开头的命令，都必须先在博客目录里执行。比如你初始化出的博客文件夹叫 my-blog，就要先cd my-blog，而不是在用户主目录下直接敲 hexo。

3. 初始化 Hexo：一条命令背后的目录逻辑

3.1 从零到本地预览：三步命令做了什么

环境就绪后，先安装 Hexo 的命令行工具。打开终端执行：

npm install -g hexo-cli

-g表示全局安装，装完之后的hexo命令在任何目录都能调用。接着用它初始化一个博客项目：

hexo init my-blog cd my-blog npm install

这三条命令要拆开理解。hexo init会从官方模板拉取一个完整的初始站点，里面已经包含默认主题和一篇示例文章；npm install则是根据模板里的依赖清单，把 Hexo 框架本体和主题依赖全部下载下来。装完后可以验证一下，再启动本地预览：

hexo version hexo server

浏览器打开http://localhost:4000，如果看到默认页面，说明整个链路已经通了。这一步非常重要，它意味着你的博客从零到一的核心机械结构已经完成，后面所有操作都是在本地先确认效果，再发布到线上。

3.2 目录结构逐项拆解：哪里放文章、哪里放配置

运行ls看一下博客目录，里面有几个关键文件夹和文件，我把它们的作用列一下，你心里就有谱了：

• _config.yml：网站全局配置文件，站点标题、语言、主题、部署目标都写在这里，YAML 格式，改完要重新生成页面才生效。
• source/：源文件目录，source/_posts/专门放文章，后面你写的东西基本都在这里。
• themes/：主题目录，每个主题一个子文件夹，换主题就是换文件夹再加改配置。
• public/：生成结果的输出目录，hexo generate会按当前内容和配置在这里重建整套页面，它是纯产物，可以随时删除重建。
• scaffolds/：模板目录，里面定义了新建文章时的初始格式。
• package.json：依赖清单，记录了这个博客装了哪些 npm 包。

刚接触时，你只需要记住一个主次关系：source/和_config.yml是你的核心资产，public/是自动生成的垃圾场，别手工去改public/里的文件，改了也会被下一次生成覆盖。

3.3 第一篇文章：Front-matter 与正文区

初始化完成后，试着创建第一篇文章：

hexo new "我的第一篇文章"

它会自动在source/_posts/下生成一个.md文件，内容开头是这样一段带横线的头信息：

--- title: 我的第一篇文章 date: 2026-01-18 10:30:00 tags: - 随笔 categories: - 生活 --- 正文从这里开始写。

这段头信息在 Hexo 里叫 Front-matter，起的是“文章元数据”的作用：标题、日期、标签、分类都定义在这里，渲染时会根据它生成文章页里的信息展示和归档索引。我建议你从第一篇开始就养成填tags和categories的习惯，因为文章数量上去之后，分类和标签就是最重要的检索入口，后期补录非常痛苦。

4. 上线到 GitHub Pages：从仓库命名到自动部署

4.1 仓库命名就是你的线上域名

本地跑通之后，下一步是把博客发布到公网。先登录 GitHub，新建一个仓库，这里有个只要写错一次就会折腾半天的规则：仓库名必须严格等于“你的用户名.github.io”。比如你的 GitHub 用户名是 demo123，仓库名就必须是 demo123.github.io，大小写也保持一致。Pages 服务的默认域名就是按照仓库名拼出来的，仓库叫什么，线上地址就是什么。

创建仓库时，免费账号要把仓库设为 Public。设置仓库为 Public 不等于代码泄露，页面效果和仓库可见性是两回事，但 Pages 服务在免费账号下只对公开仓库开放。仓库建好之后不需要往里放任何文件，空仓库就行，后面部署插件会自动把内容推进去。

4.2 部署插件与 _config.yml 末尾的配置

Hexo 默认没有部署能力，需要装一个官方推荐的插件，在博客目录里执行：

npm install hexo-deployer-git --save

然后打开_config.yml，在文件末尾加上部署配置：

deploy: type: git repo: https://github.com/demo123/demo123.github.io.git branch: main

repo地址换成你自己的仓库地址，branch填 main。这里有两个 YAML 语法上的坑要提前防住：冒号后面必须跟一个空格，缩进统一用两个空格，绝对不能用 Tab。很多人在这一步因为缩进问题吃了暗亏，后面我会专门讲排查方法。

4.3 三连命令首次发布与 token 认证

配置完成，执行发布三连：

hexo clean hexo generate hexo deploy

三条命令分工明确：clean清空上次生成留下的旧文件，generate根据当前文章重新生成整套静态页面，deploy把生成的public/目录推送到 GitHub 仓库的 main 分支。首次执行 deploy 时，Git 会要求你输入账号凭据。这里要注意，GitHub 现在已经不支持用账号密码直接推送代码了，需要先生成一个 Personal Access Token。

生成入口在 GitHub 右上角头像的 Settings 里，路径是 Developer settings → Personal access tokens，创建一个新 token，授权范围勾选 repo 相关的权限。生成后立即复制保存，当作密码粘贴到终端提示框里即可。这个 token 相当于你的专属钥匙，注意不要把它提交进博客仓库的任何文件里，丢了就在后台重新生成一个。

推送完成后，打开https://demo123.github.io，看到和本地一模一样的页面，说明你的博客已经正式上线了。首次部署后，域名解析和 HTTPS 证书生效需要几十秒到几分钟，打不开先等一会儿再刷新，别急着改配置。

5. 日常更新的完整工作流：从 Markdown 到公网文章

5.1 写作的固定节奏：新建、预览、发布

上线只是开始，真正决定博客价值的是日常能不能持续更新。我自己的固定节奏其实非常简单，就四步：新建文章、本地写作、本地预览、三连发布。

hexo new "新文章标题"

这条命令生成的新文件会套用scaffolds/post.md里的模板。我喜欢在模板里预先写好常用的 Front-matter 字段，比如固定分类、默认标签，这样每次新建都不用重复敲。写作时我用 VSCode 打开博客目录，配上 Markdown 预览插件，左边写右边看效果，完全不需要在浏览器和编辑器之间来回切。写完先本地预览，再执行hexo clean && hexo generate && hexo deploy推送上线。

5.2 Markdown 写作里最容易忽略的细节

文章写多了，有几个细节特别值得注意。第一是代码块语言标注，写技术文章时一定要在代码块开头标注语言类型，比如 bash、python、yaml，否则渲染出来没有语法高亮，阅读体验差一大截。第二是图片路径，我习惯把图片放在source/images/目录下，文章里用/images/xxx.png这样的站点相对路径引用。千万别用本地磁盘的绝对路径，也尽量别用./images这种相对路径，前者部署后必然裂图，后者在嵌套目录的文章里容易指错位置。

第三是长文结构。文章一旦超过三百行，建议拆成小标题分段，Hexo 会自动为标题生成锚点，读者可以直接跳到感兴趣的小节。另外在 Front-matter 里填一个简短的description描述，首页列表会显示这段摘要而不是整篇文章开头的一大段废话，观感会好很多。

5.3 把源码备份进第二个仓库

很多人花几个月写了几十篇文章，某天电脑硬盘坏了才追悔莫及。记住一个原则：public/里的东西是产物，删了能重新生成；source/_posts/下的每一篇 Markdown、_config.yml、主题的定制配置，才是你真正不能丢的资产。

我强烈建议你为博客源码单独建一个私有仓库做备份，把整个博客目录纳入 Git 管理，只是要在.gitignore里排除node_modules/和public/，前者是依赖可以重装，后者是生成物可以重建。操作方法：

git init git add . git commit -m "backup blog source" git branch -M main git remote add origin https://github.com/demo123/blog-source.git git push -u origin main

以后每次写完文章，发布之外顺手git add . && git commit && git push把源码推到备份仓库。好处是换电脑时只需 clone 下来、npm install一次，整个写作环境就原样恢复，连主题配置都在。

6. 我踩过的坑和排查思路

6.1 部署后 404：唯一最常发生的上线事故

如果你部署后打开线上地址得到 404，按顺序排查三个点。第一，仓库名是不是严格等于“用户名.github.io”，GitHub 对大小写敏感，很多人在用户名大小写上栽过。第二，仓库是不是 Public，免费账号的 Pages 只对公开仓库生效。第三，仓库的 Settings → Pages 页面里，Source 是否指向 main 分支，第一次 deploy 后这里通常会自动更新，但偶尔需要手动确认。

这里面最隐蔽的情况是仓库名建错了，比如建成了 blog 而不是 demo123.github.io。这样的仓库也能收到推送，但它只是个普通仓库，不会触发 Pages 服务，线上自然什么都没有。判断方法最简单：看仓库类型页面上有没有出现 Pages 相关的入口，没有就说明仓库名不对。

6.2 YAML 缩进：静默出错的元凶

如果说 404 是最高调的故障，YAML 缩进问题就是最阴险的故障。它通常不报错，或者只在 generate 时输出一行轻描淡写的警告，但后果非常实际：部署配置没生效、站点标题没变、主题切换无效、分类消失。我踩过最隐蔽的一次，是在deploy段里不小心用了 Tab 缩进，命令全部正常执行，结果页面推到了一个完全错误的目标上。

处理办法分两步。第一步，在编辑器里开启“显示空格与 Tab”选项，凡是 YAML 文件的缩进统一用两个空格，Tab 一律禁止。第二步，改完配置后执行hexo clean && hexo generate，仔细看输出里有没有 warning。YAML 解析一旦有问题，生成阶段就会透露出蛛丝马迹，比 deploy 之后才发现问题省事得多。

6.3 改了文章线上还是旧内容的三层排查

这类问题排查顺序是从本地到远端。第一层，确认你有没有执行hexo clean。如果不 clean，public/里会残留旧文件的碎片，可能出现删掉的文章还在、新文章却找不到的情况。第二层，浏览器缓存也可能让你看到旧页面，开一个无痕窗口验证最准。第三层，检查部署分支是否一致，deploy 配置里的 branch 必须是 main，而 GitHub Pages 的 Source 也要指向 main，两边不一致时推送和展示各自为政。

提示：我后来给自己定了个规矩，本地预览完直接连打三条命令hexo clean && hexo generate && hexo deploy，中间不停顿。这套固定动作执行下来，线上内容过期的概率基本降为零。

6.4 小问题速查表

踩过的坑积累多了，我整理了一张速查表，遇到类似症状可以直接对照：

经历过这几次折腾之后，我最大的体会是：搭博客最难的部分从来不是技术，而是“开始写”和“持续写”。静态博客方案已经把技术复杂度压到了极低，剩下的事情就是每天打开hexo new，写完文章顺手三连发布。如果你正准备动手，我只有一个具体建议：先本地跑通、把目录结构和主题配置都摸清楚再考虑上线，前面慢一点没关系，后面写文章的时候你会感谢当初那个不急着发布的自己。