企业官网建设流程全解析

写博客这事儿，折腾过WordPress、也用过一段时间动态站，最后我的个人博客一直固定跑在Hexo上。原因很简单：Markdown写作、Git管理、纯静态文件托管，不用养服务器也不用担心数据库被挂，发布一次到GitHub Pages之后，全世界都能用固定链接访问。这个过程里踩过的坑不少，从Node版本不兼容到主题配置失效再到图片路径神秘消失，都遇到过。这篇教程打算把完整流程重新捋一遍，无论是刚接触Hexo的新人还是想重新搭建一次的旧用户，都能照着手动搭起来，并顺手解决几个高频翻车点。

1. 内容整体设计与思路拆解

1.1 为什么选择Hexo而不是其他博客框架

先聊一下选择的问题。静态博客生成器里常见的就是Hexo、Hugo、Jekyll这几类。Jekyll和GitHub Pages原生结合最紧密，但Ruby环境在Windows上配置起来比较折磨人，主题也大多偏向极简英文风。Hugo生成速度很快，Go语言单二进制文件，但它的模板语法和内容组织方式学习曲线比Hexo陡。Hexo的优势在于Node.js生态成熟，安装只需要npm一条命令，主题和插件数量在几个框架里最多，中文社区活跃，出问题搜一下基本都有现成答案。

而且Hexo对写作者非常友好，一篇新文章就是Markdown文件加几行Front Matter，写完直接hexo g && hexo d就把整个站点生成并推送上线。不用碰Apache配置、不用处理PHP版本、不用想着备份数据库。整个博客本质就是一组静态文件，随便扔到任意Web服务都能跑，这是它的核心价值。

1.2 静态博客的整体工作流

Hexo的工作流程可以简化为：本地写Markdown文件 → Hexo生成静态页面 → 推送到托管平台。中间的细节是，每篇文章由Front Matter（标题、日期、标签、分类）和正文组成，Hexo会把这些信息渲染成HTML页面，同时生成归档页、标签页、首页的分页列表。因为输出是纯静态页面，访问速度快，不依赖后端逻辑，所以不存在被攻击注入的问题，也不怕高流量把服务器打挂。

整个发布链路里最核心的两个命令就是hexo g（generate生成）和hexo d（deploy部署）。很多初期用户会混淆这两个命令，实际上先执行hexo g再执行hexo d就对了。如果修改了配置或主题文件，还需要先hexo clean清掉缓存再重新生成，否则经常碰到改动不生效的怪问题。这套流程我用了几年，稳定得离谱，除了偶尔换主题重新生成以外基本没出过岔子。

1.3 部署目标选型：GitHub Pages为主，其他方案为辅

Hexo生成出来的静态文件可以部署到很多地方：GitHub Pages、Gitee Pages、Netlify、Vercel，甚至一个简单的Nginx服务器都行。这里优先讲GitHub Pages，因为它是GitHub官方免费提供的托管服务，仓库地址就是站点地址，配合Git操作链非常顺滑，也不用交任何费用。

要注意的是GitHub Pages分为两种：个人/组织站点和项目站点。个人站点仓库名必须叫用户名.github.io，构建出的站点地址就是https://用户名.github.io。项目站点则可以是任意仓库，地址变成https://用户名.github.io/仓库名/。对个人博客来说，直接创建用户名.github.io这种仓库最省事，不用额外处理子路径问题。

2. 核心细节解析与实操要点

2.1 环境准备：Node.js的版本选择

Hexo是Node.js生态里的工具，所以第一步永远是装Node.js。版本选择上，我建议装LTS版（长期支持版），不要追求最新尝鲜版。Node的版本对Hexo的影响很直接，如果版本太高或太低，都可能出现node-sass这类原生模块编译失败的情况，报错日志里常看到Failed at the node-sass@版本号 postinstall script。避免这个问题最省心的方式就是使用LTS版，并保持npm源正常，然后安装Hexo CLI。

检查环境是否就绪只需要两个命令：

node -v npm -v

能看到版本号就说明Node和npm装好了。如果提示找不到命令，一般就是路径没加入环境变量，Windows用户重新安装时记得勾选“Add to PATH”。

2.2 安装Hexo与博客目录初始化

环境没问题之后，用npm全局安装Hexo命令行工具：

npm install hexo-cli -g

接着在一个干净的目录里初始化博客：

hexo init blog cd blog npm install

hexo init会自动拉取一套Hexo默认模板站点，包括基础目录结构、config文件和landscape主题。npm install则是根据模板里的依赖清单安装所有需要用到的模块。这个初始化过程完成后，直接运行hexo s，浏览器访问http://localhost:4000就能看到默认站点。

这里有一个实际操作中的心得：hexo init成功后建议先进_config.yml把站点标题等基础信息改了再继续折腾主题，不然每次刷新页面都看到Hello World，心态上总觉得没搭好，其实只是默认内容而已。

2.3 目录结构理解

初始化生成的目录结构是Hexo约定好的，必须理解每个文件夹的用途才能高效使用。核心的几个如下：

• source/：存放所有文章源文件，.md后缀的文件就是博客文章，_posts目录下的Markdown文件会被渲染为文章页面。另外source里还可以放about、tags、categories等自定义页面文件，这些会原样生成到站点根目录。
• themes/：存放主题，每个主题是一个独立文件夹，里面有layout模板文件夹、source静态资源文件夹和_config.yml主题配置文件。
• scaffolds/：脚手架模板，执行hexo new时用来生成文章模板，可以自己改动模板内容。
• _config.yml：站点级配置文件，站点标题、URL、语言、主题名称、部署配置全在这里。

记住一个原则：写文章只动source/_posts，换样式改themes，全局设置才动根目录的_config.yml。刚上手的人最容易把三个东西混在一起，改错配置哪都出问题，但说不清为什么。

3. 实操过程与核心环节实现

3.1 站点基础配置修改

进到博客根目录，打开_config.yml。这个文件是整个Hexo的起点，先改这几个关键字段：

title: 你的站点名 subtitle: 副标题 description: 站点描述 author: 作者名 language: zh-CN timezone: Asia/Shanghai

其中language很关键，改成zh-CN后，插件和主题的界面语言会变成中文。url字段初次配置时可以先用https://你的用户名.github.io占位，等部署完GitHub Pages以后再改过来，因为这个字段是生成sitemap和canonical链接的基础。

改了_config.yml之后，用hexo clean && hexo g重新生成，再hexo s预览，确认标题等信息生效。这里要记住清理缓存，因为很多故障都是旧缓存导致的页面不更新。

3.2 安装一款好用的主题

默认主题landscape比较基础，一般都会换掉。主题选择上，初学者推荐Next主题或Butterfly主题。Next主打极简双栏，配置项精简，文档清晰；Butterfly功能更丰富，支持背景图、卡片样式、代码高亮等，颜值高但配置也更多。我个人偏向Next，因为稳定性和视觉效果在中长期使用中很舒服。

以Next为例，安装方式直接：

git clone https://github.com/theme-next/hexo-theme-next.git themes/next

然后在根目录_config.yml把theme字段改为next。很多主题还支持通过npm安装，那就要按主题文档来操作，不要混用。

换完主题之后，注意主题也有一个_config.yml，位置在themes/next/_config.yml。这个是主题的配置入口，菜单显示哪几项、侧栏展示什么、开启哪些功能，都在这里调。但记住一个坑：根目录_config.yml和主题目录_config.yml是两个不同的文件，位置别搞混。根目录管全局，主题目录管外观样式，改到哪里都会多少出问题。

3.3 写文章与Front Matter格式

写作流程很简单，执行：

hexo new "文章标题"

这会按scaffolds/post.md里的模板在当前时间创建一个新Markdown文件，路径类似source/_posts/2024-01-01-文章标题.md。这个文件开头有一段Front Matter：

--- title: 文章标题 date: 2024-01-01 12:00:00 tags: - 标签1 - 标签2 categories: 分类 ---

这些字段会被用来生成文章页、归档页和分类页。title会作为页面标题，tags和categories是组织内容的维度。一些主题还支持cover、description等自定义字段，这些能提升文章在博客首页的展示效果。

写作正文部分就是纯Markdown，正常写二级标题、正文段落、代码块就行了。注意Front Matter的冒号后面必须有空格，不然yaml解析会出错，生成时报empty value之类的错。很多新人卡在这一步，报错原因是解析器不认识那个字段。

3.4 图片与静态资源处理

图片处理是Hexo使用里非常容易踩坑的环节。有两种常见处理方式。

第一种是配合post_asset_folder开关使用。在根目录_config.yml里设置：

post_asset_folder: true

这样每次新建文章时，source/_posts会同步创建一个同名的图片文件夹，把图片放进这个文件夹，然后在文章里用相对路径引用。这适合单篇文章配图很多、需要集中管理的场景。

第二种是新建source/images文件夹，把全站共享的图放进去，文章里用/images/xxx.jpg引用。这种方式适合logo、头像、站点背景图这类全局资源。

两个方案都不复杂，关键是要想清楚哪类图片走哪个路径。有个从实践中来经验：尽量少用图床，因为图床的图片外链随时可能失效，而你的博客是要长期存在的。图片放本地文件夹里，哪怕空间大点也踏实，Git维护也方便。

3.5 部署到GitHub Pages

部署是Hexo使用里另一道门槛，但也只是几步。先在GitHub上创建一个新仓库，仓库名必须是你的GitHub用户名.github.io。创建时不要勾选添加README，保持空仓库，这样待会儿推送时不容易产生冲突。

然后在博客根目录_config.yml最下面找到deploy配置段：

deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main

注意type默认是git，而不是GitHub。接着安装部署插件：

npm install hexo-deployer-git --save

之后每次发布执行：

hexo clean && hexo g && hexo d

hexo d会自动把站点生成目录public/（对这个插件来说，实际是临时目录）里的内容推送到你配置的仓库分支。推完之后，浏览器访问https://你的用户名.github.io就能看到你的博客了。首次推送后几分钟内页面可能显示404，这是正常的，等GitHub构建好就会恢复。

3.6 自定义域名与HTTPS配置

如果你的博客想用自己的域名而不是用户名.github.io，在部署配置之外还需要做两件事：第一，在仓库设置里的Pages页面，填上你的自定义域名；第二，在DNS服务商那边添加一条CNAME或A记录。

建议直接在本地source目录建一个名为CNAME的文件，内容就写一行你的域名，比如blog.example.com。这样做的好处是每次hexo d推送后，文件都会跟着进仓库，GitHub Pages不会因为生成过程丢失自定义域名配置。域名解析记录添加完，就能通过个人域名访问博客，GitHub会自动签发HTTPS证书，这个不用额外配置，稍等生效就行。

3.7 多语言站点配置

多语言这个功能如果一开始没规划好，后面改起来比较费劲。但规划好其实也不难。Hexo的多语言方案大致有两种。

第一种是使用官方多语言插件hexo-generator-i18n。这个插件支持生成多语言首页和文章副本。安装之后需要在_config.yml里配置支持的语种和默认语言：

language: - zh-CN - en i18n: generator: posts: false pages: false

使用这个插件时，文章的Front Matter里写上lang: zh-CN或lang: en，插件会按语言归类文章。这种方式的优点是结构清晰，用/en路径访问英文内容，/访问中文内容。缺点是需要为同一篇文章写多个语言版本，内容维护成本高。

第二种是NexT主题自带的多语言界面。这类主题本身支持界面文字按语言切换，_config.yml里的language设为zh-CN时，菜单、按钮、分页这些界面元素全变中文。这种方式的“多语言”侧重于界面语言，而不是内容语言。如果你只是想让主题界面显示中文，直接把language改成zh-CN就行，并不需要额外的插件。

如果要做真正的双语博客，我建议用插件方案，因为内容和界面分开管理，结构更干净。英文环境（hexo s -l en）和中文环境各看各的文章，不会互相干扰。踩过的小坑是插件版本和主题兼容的问题，务必先读插件文档确认用法，再动手改配置。

4. 常见问题与排查技巧实录

下面这些问题都是实操中反复遇到的典型故障，整理成速查表，直接对照解决就行。

4.1 Windows环境下端口冲突与权限问题

Windows系统跑Hexo最常见的是端口冲突和权限问题。有一次我执行hexo s，终端提示EADDRINUSE，一看就知道4000端口被占了。解决办法很简单，用hexo s -p 8000换个端口就行。这不算什么大事，但如果每次都遇上也怪烦的，查一下是什么程序占用端口并关掉更好。

另一个Windows特有的问题是PowerShell执行策略限制脚本执行。如果安装依赖或执行命令时报权限错误，试试用管理员身份运行终端，或者把执行策略调整为RemoteSigned。

4.2 部署GitHub Pages时的三类坑

第一类坑是仓库名字不对。GitHub Pages个人站点要求仓库名严格等于用户名.github.io，如果建错了名字，页面永远不会出现在预期地址上。

第二类坑是分支名不一致。新仓库默认分支可能是master也可能是main，GitHub现在默认用main。_config.yml里的branch字段必须与实际分支一致，推错了地方部署自然失败。

第三类坑是Git凭据问题。部署推送时需要登录GitHub账号，如果本机Git配置过其他账号，可能推送时报权限不足。可以用git config --list查看当前账号，必要时单独配置本项目内的用户名和邮箱。

4.3 主题和插件兼容性问题

主题和插件的兼容是很多疑难问题的根源。比如某些主题基于NexT的旧版本开发，但插件升级到新版本后接口变了，主题渲染就异常。这种情况没有万能解，但有一个排查思路：锁定版本。在package.json里把已知能用的插件版本固定住，不要轻易升级。Hexo本身也一样，版本大版本升级时要先看官方升级日志，再决定要不要跳版本。

另一个心得是，不要同时装一大堆功能相似的主题和插件。主题只能启用一个，插件装得过多反而拖慢生成速度，还可能互相冲突。能用主题自带的功能解决的就不要额外装插件，保持依赖清单越干净，博客寿命越长。

4.4 备份与迁移

博客写多了以后，最担心的就是本地电脑出问题导致文章丢失。Hexo的文章是本地文件，这种风险是客观存在的，解决方式就是保持整个博客目录纳入Git管理。

在hexo init后马上执行：

git init git add . git commit -m "initial"

之后每次写完文章提交一次，把仓库推到GitHub的另一个私有仓库里（别和Pages仓库混淆）。这样换电脑时只需要克隆仓库、npm install、npm install hexo-cli -g，整套环境就恢复了。这个操作属于一次性投入长期受益，强烈建议第一时间做。

5. 实战演练：从零搭建一个完整博客

上面分步讲了很多，但要形成一个整体流程，最好还是跟着完整跑一遍。下面用一个实际场景把全部环节串起来：从新电脑开始，到最后发布上线并配置多语言。

5.1 全流程命令实录

在一台装好Node的机器上，依次执行下面这些命令就能跑通全流程：

# 安装Hexo CLI npm install hexo-cli -g # 初始化博客 hexo init myblog cd myblog # 安装依赖 npm install # 本地预览 hexo s

预览确认无误后，修改基础配置：

# 打开_config.yml，修改title、author、language、url等

安装主题：

git clone https://github.com/theme-next/hexo-theme-next.git themes/next

修改根目录_config.yml中theme: next，同时设置language: zh-CN。

创建第一篇文章：

hexo new "我的第一篇博客"

编辑文章Markdown文件，写点内容，然后生成并预览：

hexo clean && hexo g hexo s

本地确认无问题，去GitHub创建用户名.github.io仓库，配置部署字段：

deploy: type: git repo: https://github.com/用户名/用户名.github.io.git branch: main

安装部署插件并发布：

npm install hexo-deployer-git --save hexo clean && hexo g && hexo d

等上几分钟，访问https://用户名.github.io，博客就正式上线了。

5.2 多语言配置实战

想在这里加一个英文版本入口，就按这个方式做。先安装多语言插件：

npm install hexo-generator-i18n --save

再修改_config.yml：

language: - zh-CN - en i18n: generator: posts: false pages: false

写文章时在Front Matter里加lang: en标记英文文章：

--- title: Hello Hexo lang: en ---

中文文章就保留lang: zh-CN。访问/en路径，就能看到英文内容的独立站点配置。再为中文文章建分类和标签页，每个页面也要考虑语言版本，不过这一步可以根据博客的规划慢慢加。

5.3 上线后的日常维护任务清单

上线不等于完事，博客日常保养也是要做的。我列一份操作清单，照着做就行：

• 每次升级Node或Hexo前，先把博客整个备份提交到Git仓库。
• 定期检查hexo g生成过程有无警告信息，有就顺手修掉。
• 每发布几篇文章后，用hexo sitemap生成站点地图，方便搜索引擎收录。
• 域名如果换了，记得同时更新DNS和_config.yml里的url字段，保持链接一致性。
• 保持订阅功能开启，很多主题自带RSS生成，配好Feed插件后读者才能方便订阅。
• 主题和插件安装前看GitHub仓库的星标、更新日期，别选长期不维护的来用。

实际用下来，Hexo真的是那种“折腾一次，受用很久”的工具。初始搭建那几天可能会遇到各种小问题，但配置一旦稳定，后面写文章就完全专注在内容上了，再也不用关心服务器状态、数据库连接这类事情。我个人体会最深的一点是，不要把博客搭建这件事变成一个无休止的主题美化工程，先能把文章发出去，再逐步优化结构和样式，这样节奏舒服，效果也更好。