Hexo搭建技术博客使用与常见问题详细讲解

发表于 2018-04-26 更新于 2025-11-30 分类于 hexo 阅读次数：本文字数： 9.1k 阅读时长 ≈ 8 分钟

折腾Hexo这货已经有一段时间了，之前也不愿意去看官方文档，到处搜索如何搭建，如何设置等等，但是有时也无法找到自己想要的内容，于是只能研究官方文档了。最近静下心来，把Hexo Docs从头看了一遍，这里将官网Docs加上自己的一些理解记录下来。

hexo

官方Docs分为了4个部分，分别为：开始准备、基础用法、自定义、其他。Hexo的主要内容是在基础用法和自定义这两部分上。这部分主要介绍了什么是Hexo、如何安装以及基本配置。

Hexo是一个快速的、简单的、功能强大的博客框架。你可以通过Markdown语言写文章，然后hexo帮你生成一个带有漂亮主题的静态页面。

安装

安装hexo的前提是要有Node.js以及Git，至于什么是Git和Node以及如何安装他们可以自行搜索了解。
安装完Node以及Git后，通过下面的命令安装Hexo:npm install -g hexo-cli

启动

在电脑中找个目录，并进入目录，执行下面几个命令，hexo就准备就绪了。

1 2	hexo init npm install

上面两条命令，第一条是初始化目录，会自动生成一些基础文件和目录，第二条命令是安装运行hexo的一些必要的组件。
OK，运行完，你会看到你的当前目录下，会自动创建一些目录，如下：

├── _config.yml
├── package.json
├── scaffolds/
├── scripts/
├── source/
|   ├── _drafts
|   └── _posts
└── themes/

下面依次介绍上面各个文件或者目录的用途：

_config.yml 站点配置文件，很多全局配置都在这个文件中。
package.json 应用数据。从它可以看出hexo版本信息，以及它所默认或者说依赖的一些组件。
scaffolds 模版文件。当你创建一篇新的文章时，hexo会依据模版文件进行创建，主要用在你想在每篇文章都添加一些共性的内容的情况下。
scripts 放脚本的文件夹，就是放js文件的地方
source 这个文件夹就是放文章的地方了，除了文章还有一些主要的资源，比如文章里的图片，文件等等东西。这个文件夹最好定期做一个备份，丢了它，整个站点就废了。
themes 主题文件夹。

配置

前面说了，主要配置就是_config.yml这个文件了，所以来看看怎么配置它了。配置也是分了几个大块的。

1. 站点部分参数设置：

title 站点名字，也就是html的title，会显示在浏览器标签上。
subtitle 站点副标题，会显示在首页上，可以不填。
description 站点描述，可以不填。
author 作者
language 语言
timezone 站点时区，默认是电脑时间

2. URL部分设置：

url 站点网址
root 站点根目录
permalink 文章的永久网址链接，默认是:year/:month/:day/:title/，指的什么意思？比如我一篇叫『love』的文章是在2012年1月1日写的，那么它对应的链接就是http://yoururl/2012/01/01/love/
permalink_default 如果网址是次级目录，比如：http://example.com/blog，那么就要设置url为http://example.com/blog，并且root要设置为/blog/。

3. 目录配置：

source_dir source目录，默认值为source
public_dir public目录，静态网站生成的地方，默认值为public
tag_dir tag目录
archive_dir Archive目录
category_dir 分类目录
code_dir 代码目录
i18n_dir i18n目录
skip_render 不想被渲染的路径
上面这一部分的值，我基本上没有改过，默认的就行了。

4. 写作配置：

new_post_name 新建文章默认文件名，默认值为 :title.md，比如你执行命令hexo new hello，就会默认在_post目录下创建一个hello.md的文件。
default_layout 默认布局
titlecase
external_link 在新标签中打开一个外部链接，默认为true
filename_case 转换文件名，1代表小写；2代表大写；默认为0，意思就是创建文章的时候，是否自动帮你转换文件名，默认就行，意义不大。
render_drafts 是否渲染_drafts目录下的文章，默认为false
post_asset_folder 是否启用Asset Folder，默认为false，至于什么是Asset Folder，后面有讲解。
future 是否显示未来日期文章，默认为true
highlight 代码块设置
这一部分也可以基本不变，默认值就行。

5. 文章属性：

文章可以拥有如下属性

-	Setting	Description	Default
1	layout	Layout	post或page
2	title	文章的标题
3	date	创建日期	文件的创建日期
4	updated	修改日期	文件的修改日期
5	comments	是否开启评论	true
6	tags	标签
7	categories	分类
8	permalink	url中的名字	文件名
动态博客中通过发布文章页面设置的各种属性，在hexo里要这样设置。

6. 分类和标签的设置：

default_category 默认分类，默认为无分类，当然你可以设置一个默认分类。
category_map 分类，不明白其作用
tag_map 标签，不明白其作用

7. 日期和时间格式配置：

Hexo使用的Moment.js来处理时间的。
data_format 日期格式，默认为MMM D YYYY，不过我将它改成了YYYY-MM-DD，符合个人口味，其他格式模版可以查看Moment.js
time_format 时间格式，默认为H:mm:ss

8. 分页设置：

per_page 一页显示多少篇文章，0 为不分页，默认值为 10
pagination_dir 分页目录，默认值为page

9. 扩展配置：

theme 主题配置，此处填上主题名就OK了，当然在themes目录下一定要有你配置的主题文件夹。
deploy 部署配置，将本地public目录也就是网站部署到服务器上的配置。如何部署？Docs文档『基础用法』部分有说明。

10.跳过渲染

如果只有一个HTML文件的话，可以简单地在文件开头加上layout: false一行即可：

layout: false
---

<html>
...

如果有多个要避开渲染的md文件，显然是不可能使用这种方法的。这时候需要使用skip_render配置。根据Hexo文档中的说明，通过在_config.yml配置文件中使用skip_render参数，可以跳过指定文件的渲染。使用方式如下：

skip_render: [games/**, depview/**, knowledge/**]
这里的路径匹配可以使用正则表达式。

注意：skip_render参数设置的路径是相对于source目录的路径。例如，需要跳过渲染source/README.md，只需要设置 skip_render:README.md。
在设置了跳过渲染之后，最好使用hexo clean清除以前的编译结果，保证配置生效

命令

这块主要介绍了hexo的一些命令的使用方法，Hexo 约有二十个命令，但普通用户经常使用的大概只有几个。
hexo init [folder]，使用该命令初始化一个站点，不加目录参数，就初始化当前目录
hexo new [layout] <title>，创建一篇文章，如果不指定layout，那么就使用_config.yml中default_layout的值，标题中如果有空格，将整个title放到引号中。比如，hexo - - new "hello world"创建一篇叫hello world的文章。标题里有空格，所以加上了引号、文章标题可以在对应 md 文件里改，新建时标题可以写的简单些、hexo n 是 hexo new 的缩写，命令效果一致。
hexo generate，简单的说，这个命令就是将md格式的文章，生成网站静态文件到默认设置的 public 文件夹。这个命令可以简写为hexo g，便于查看网站生成的静态文件或者手动部署网站；如果使用自动部署，不需要先执行该命令；它有两个参数选项：
- -d,–deploy 生成完后直接部署
- -w,–watch 查看文件的改变
hexo server，启动一个本地服务，用于预览主题。可以在本地查看网站，hexo s 是 hexo server 的缩写，命令效果一致、预览的同时可以修改文章内容或主题代码，保存后刷新页面即可、对 Hexo 根目录 _config.yml 的修改，需要重启本地服务器后才能预览效果、默认启动http://localhost:4000，貌似这个不是默认，运行命令的时候可以查看提示消息。它也有一些参数：
- -p,–port 指定端口
- -s,–static 仅服务静态文件
- -l,–log 开启日志
hexo publish [layout] <filename>，发布一个草稿
hexo deploy 部署站点，hexo d 是 hexo deploy 的缩写，命令效果一致，有一个参数，hexo d -g表示在部署前先重新生成一下站点、并部署到设定的仓库。
hexo render <file1> [file2] ... 渲染文件，具体我也不太明白这是干嘛的
hexo migrate <type> 迁移其他博客系统的命令，具体怎么使用DOCS后面有介绍。
hexo clean 删除缓存文件db.json以及生成的public目录，当你修改了某些样式或者配置时，如果发现hexo g后也没有反应，网站显示异常时、就可以执行一下这个命令。
hexo n page例如：hexo n page aboutme新建一个标题为 aboutme 的页面，默认链接地址为 主页地址/aboutme/标题可以为中文、但一般习惯用英文、页面标题和文章一样可以随意修改、页面不会出现在首页文章列表和归档中，也不支持设置分类和标签。
hexo list 没用过
hexo version 显示版本信息
hexo --safe 安全模式，使所有插件和脚本不生效
hexo --dehug 调试模式
hexo --silent 静默模式，不在终端上显示任何信息
hexo --config custom.yml 使用一个自定义配置文件替换默认_config.yml
hexo --draft 显示草稿文章（位于source/_drafts目录下）
hexo --cwd /path/to/cwd 自定义当前工作目录路径，假如你没在工作目录下，可以使用这个命令指定一下工作目录路径。

常用组合命令

1 2	hexo clean && hexo s hexo clean && hexo d

可以用输入法等软件为这些命令设置快捷键，方便调用。

需要删掉用命令新建的文章或页面时，只需要进入 Hexo 根目录下的 source 文件夹，删除对应文件或文件夹即可；

更多命令用法请查询官方文档。

迁移

从其他博客站点迁移文章到hexo中，像类似Jekyll和Octopress只要把.md的文章拷贝过来就OK了，还有一些需要安装插件。

RSS：首先安装插件npm install hexo-migrator-rss --save，待安装完成后，运行命令hexo migrate rss <source>就可以从RSS迁移所有文章了。source可以是一个文件路径或者URL
Jekyll & Octopress：直接拷贝_posts文件夹里的文章到hexo的source/_posts就OK了，然后修改new_post_name参数为对应文章title命名规则就行了，如:year-:month-:day-:title.md
WordPress：安装插件npm install hexo-migrator-wordpress --save，使用WordPress导出功能导出文章，然后运行命令hexo migrate wordpress <source>，source为导出文件
Joomla：安装插件npm install hexo-migrator-joomla --save，使用J2XML组件导出Joomla文章，然后运行命令hexo migrate joomla <source>，source为导出文件导出或者导入，可能出现一些问题，可以自行百度搜索。

草稿

草稿相当于很多博客都有的“私密文章”功能。新建草稿文件hexo new draft "new draft"会在source/_drafts目录下生成一个new-draft.md文件。但是这个文件不被显示在页面上，链接也访问不到。也就是说如果你想把某一篇文章移除显示，又不舍得删除，可以把它移动到_drafts目录之中。
如果你希望强行预览草稿，更改配置文件：render_drafts: true或者，如下方式启动server：hexo server --drafts
下面这条命令可以把草稿变成文章，或者页面：hexo publish [layout] <filename>

常见问题记录

1. Cannot find module swig

ERROR Plugin load failed: hexo-deployer-git
Error: Cannot find module 'swig'
    at Function.Module._resolveFilename (module.js:536:15)
    at Function.Module._load (module.js:466:25)
    at Module.require (module.js:579:17)
    at require (internal/module.js:11:18)
    at Object.<anonymous> (E:\01-blog-space\hexo\node_modules\_hexo-deployer-git@0.3.1@hexo-deployer-git\lib\deployer.js:6:12)
    at Module._compile (module.js:635:30)
    at Object.Module._extensions..js (module.js:646:10)
    at Module.load (module.js:554:32)
    at tryModuleLoad (module.js:497:12)
    at Function.Module._load (module.js:489:3)
    at Module.require (module.js:579:17)
    at require (E:\01-blog-space\hexo\node_modules\hexo\lib\hexo\index.js:216:21)

问题解决：安装npm install swig --save

2. 端口占用

这种情况一般是因为4000端口被占用，使用下面的命令更改端口号为5000 然后浏览器输入http://localhost:5000/
可是每次这样设置会很麻烦（如果4000端口被占用）
解决办法： 在站点配置文件加入

server:
  port: 5000
  compress: true
  header: true

跳过指定文件的渲染

关于hexo的_config.yml配置，官方文档中：skip_render：跳过指定文件的渲染，您可使用 glob 表达式来匹配路径。但并没有说明具体该怎么配置，一番折腾后得以解决、如果要跳过source文件夹下的test.html，可以这样配置：skip_render: test.html、
注意，千万不要手贱加上个/写成/test.html，这里只能填相对于source文件夹的相对路径。
如果要忽略source下的test文件夹下所有文件，可以这样配置：skip_render: test/*
如果要忽略source下的test文件夹下.html文件，可以这样配置：skip_render: test/*.html
如果要忽略source下的test文件夹下所有文件和目录，可以这样配置：skip_render: test/**
如果要忽略多个路径的文件或目录，可以这样配置：

1
2
3

skip_render:
    - test.html
    - test/*

Tips:
如何不处理source目录下某个子目录的所有文件，仅仅是将其copy到public目录中对应目录？

yelee主题搜索问题

后来删除node_modules重新安装依赖后发现TMD的又好了、哎！！！

前段时间更新了hexo-generator-search的版本为^2.4.0，结果发现发布后搜索时点击搜索结果没有效果了，并不会跳转到对应的搜索结果页面去，经过一番找问题发现了问题:
从themes/skyheng/source/js/search.js中可以查看到会从search.xml取var data_url = data.url;，然后拼接连接如下

1	str += "<li><a href='"+ data_url +"' class='search-result-title' target='_blank'>"+ "> " + data_title +"</a>";

然后在public文件夹中查看版本为^2.4.0生成的search.xml发现里面并没有url节点

<entry> 
  <title>Hexo搭建技术博客使用与常见问题详细讲解</title>  
  <link href="/post/50982.html"/>  
  <content type="html"></content>  
  <categories> 
    <category>hexo</category> 
  </categories>  
  <tags> 
    <tag>hexo</tag> 
  </tags> 
</entry>

然后把hexo-generator-search的版本号改为^2.2.5后发现再次生成的search.xml就有url节点

<entry> 
  <title>Hexo搭建技术博客使用与常见问题详细讲解</title>  
  <link href="/post/50982.html"/>
  <url>/post/50982.html</url>
  <content type="html"></content>  
  <categories> 
    <category>hexo</category> 
  </categories>  
  <tags> 
    <tag>hexo</tag> 
  </tags> 
</entry>

这样search.js的方法searchFunc就可以取值到url的节点的值了，问题就解决了。

升级

更换了新主题，在hexo g和hexo s的时候总会报如下错误，在主题github issues逛了一圈后，感觉应该是我的hexo版本太老了。

➜ hexo s
(node:64285) [DEP0061] DeprecationWarning: fs.SyncWriteStream is deprecated.
INFO  Start processing
ERROR Process failed: layout/archive.ejs
SyntaxError: Invalid or unexpected token in "D:\blog-space\hexo\themes\hexo-theme-matery\layout\archive.ejs"
    at new Function (<anonymous>)
    at Object.exports.compile (D:\blog-space\hexo\node_modules\ejs\lib\ejs.js:242:14)
    at Function.ejsRenderer.compile (D:\blog-space\hexo\node_modules\hexo-renderer-ejs\lib\renderer.js:11:14)
    at Theme._View.View.View._precompile (D:\blog-space\hexo\node_modules\hexo\lib\theme\view.js:117:31)

决定升级hexo版本，但是没找到很明确的升级hexo的文章，遂做一下记录。

1、全局升级hexo-cli，先hexo version查看当前版本，然后npm i hexo-cli -g，再次hexo version查看是否升级成功。

2、使用npm install -g npm-check和npm-check，检查系统中的插件是否有升级的，可以看到自己前面都安装了那些插件

3、使用npm install -g npm-upgrade和npm-upgrade，升级系统中的插件

4、使用npm update -g和npm update --save

5、清除npm cache npm cache clean -f # 清除node.js的cache

Hexo版本升级和Next主题升级之坑 https://blog.csdn.net/u014253173/article/details/81088518

资料

hexo博客：http://lupeng.me/categories/%E6%8A%80%E6%9C%AF/Hexo/
图灵社区hexo合集：http://www.ituring.com.cn/minibook/29442