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

折腾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,运行完,你会看到你的当前目录下,会自动创建一些目录,如下:

1
2
3
4
5
6
7
8
├── _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一行即可:

1
2
3
4
5
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.ymldefault_layout的值,标题中如果有空格,将整个title放到引号中。比如,hexo - - new "hello world"创建一篇叫hello world的文章。标题里有空格,所以加上了引号、文章标题可以在对应 md 文件里改,新建时标题可以写的简单些、hexo nhexo new 的缩写,命令效果一致。
  • hexo generate,简单的说,这个命令就是将md格式的文章,生成网站静态文件到默认设置的 public 文件夹。这个命令可以简写为hexo g,便于查看网站生成的静态文件或者手动部署网站;如果使用自动部署,不需要先执行该命令;它有两个参数选项:
    • -d,–deploy 生成完后直接部署
    • -w,–watch 查看文件的改变
  • hexo server,启动一个本地服务,用于预览主题。可以在本地查看网站,hexo shexo server 的缩写,命令效果一致、预览的同时可以修改文章内容或主题代码,保存后刷新页面即可、对 Hexo 根目录 _config.yml 的修改,需要重启本地服务器后才能预览效果、默认启动http://localhost:4000,貌似这个不是默认,运行命令的时候可以查看提示消息。它也有一些参数:
    • -p,–port 指定端口
    • -s,–static 仅服务静态文件
    • -l,–log 开启日志
  • hexo publish [layout] <filename>,发布一个草稿
  • hexo deploy 部署站点,hexo dhexo 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了,还有一些需要安装插件。

  1. RSS:首先安装插件npm install hexo-migrator-rss --save,待安装完成后,运行命令hexo migrate rss <source>就可以从RSS迁移所有文章了。source可以是一个文件路径或者URL
  2. Jekyll & Octopress:直接拷贝_posts文件夹里的文章到hexo的source/_posts就OK了,然后修改new_post_name参数为对应文章title命名规则就行了,如:year-:month-:day-:title.md
  3. WordPress:安装插件npm install hexo-migrator-wordpress --save,使用WordPress导出功能导出文章,然后运行命令hexo migrate wordpress <source>,source为导出文件
  4. 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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端口被占用)
  • 解决办法: 在站点配置文件加入
1
2
3
4
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.xmlvar 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节点

1
2
3
4
5
6
7
8
9
10
11
<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节点

1
2
3
4
5
6
7
8
9
10
11
12
<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版本太老了。

1
2
3
4
5
6
7
8
9
➜ 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-checknpm-check,检查系统中的插件是否有升级的,可以看到自己前面都安装了那些插件

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

4、使用npm update -gnpm update --save

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

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

资料

个人微信公众号技术交流QQ群
文章目录
  1. 1. 安装
  2. 2. 启动
  3. 3. 配置
    1. 3.1. 1. 站点部分参数设置:
    2. 3.2. 2. URL部分设置:
    3. 3.3. 3. 目录配置:
    4. 3.4. 4. 写作配置:
    5. 3.5. 5. 文章属性:
    6. 3.6. 6. 分类和标签的设置:
    7. 3.7. 7. 日期和时间格式配置:
    8. 3.8. 8. 分页设置:
    9. 3.9. 9. 扩展配置:
    10. 3.10. 10.跳过渲染
  4. 4. 命令
    1. 4.1. 常用组合命令
  5. 5. 迁移
  6. 6. 草稿
  7. 7. 常见问题记录
    1. 7.1. 1. Cannot find module swig
    2. 7.2. 2. 端口占用
  8. 8. 跳过指定文件的渲染
  9. 9. yelee主题搜索问题
  10. 10. 升级
  11. 11. 资料