Hexo搭建静态博客过程
环境
项目 | 版本 |
---|---|
OS | Linux 5.10.102.1 WSL Ubuntu 22.04.2 LTS |
node.js | v18.18.0 |
hexo-cli | 4.3.1 |
hexo | 6.3 |
next | 8.18.1 |
搭建环境
1. 方案一:在Linux系统中安装所需环境
⑴ 安装node.js
Hexo官方推荐[1]使用NodeSource的发布:GitHub
⑵ 替换为国内源
设置为阿里源
npm config set registry https://registry.npmmirror.com
sudo npm config set registry https://registry.npmmirror.com
检查是否设置成功
npm config get registry
sudo npm config get registry
⑶ 安装Hexo-CLI和Hexo库
根据官方文档^[2]^安装:
npm install -g hexo-cli --verbose # 可能要使用sudo
npm install hexo --verbose #文档中有,但是貌似不用
2. 方案二:使用Docker搭建环境
⑴ 准备Docker镜像
从node.js官方的Docker镜像搭建Hexo环境。一种Dockerfile如下[22.b]:
1 | FROM node:18.18.0-slim |
运行[22.b]
build.shdocker build -t hexo:hexo6.3.0-cli4.3.1-node18.18.0-slim . --build-arg "HTTP_PROXY=http://172.26.128.1:7890" --build-arg "HTTPS_PROXY=http://172.26.128.1:7890"
即可编译为镜像。
该镜像已经提交到xiaosiyu0603/hexo:hexo6.3.0-cli4.3.1-node18.18.0-slim
[22.a],可以运行[22.b]
docker pull xiaosiyu0603/hexo:hexo6.3.0-cli4.3.1-node18.18.0-slim
下载。
⑵ 根据Docker镜像构建运行容器
运行[22.b]
run.shdocker run -it --rm -p 64000:4000 -v /etc/passwd:/etc/passwd:ro -v /etc/group:/etc/group:ro -v $HOME:$HOME -v $(pwd):$(pwd) -u $(id -u):$(id -g) -w $(pwd) xiaosiyu0603/hexo:hexo6.3.0-cli4.3.1-node18.18.0-slim
即可将在当前路径运行Hexo环境,并且将当前路径映射到容器中,同时将容器的4000端口映射到主机的64000端口上[21],最后进入终端bash
。
建站
1. 新建Hexo工作目录
新建一个空白目录作为工作目录,例如/hexo-site
,然后执行
cd /hexo-site
hexo init .
npm install
即可部署Hexo所需文件[2]。这些文件的介绍亦参考[2]。
若无额外说明,后文执行命令均在工作目录/hexo-site
下执行。
2. 建立Git仓库以便进行管理
git init
不建议在新建Hexo工作目录之前创建仓库,因为hexo init
要求空白目录。
3. 从克隆的仓库开始
*注:*新建网站忽略这一步。
仓库中不会储存包的文件,运行
npm install --verbose
安装package.json
中所记录的包,否则这些包缺失。
有些包需要从GitHub下载,需要配置代理方可正常安装,--verbose
参数可以帮助判断卡在了什么位置。
4. Hexo配置文件
网站的配置在根目录的_config.yml
中修改,详情参考[3]。
关于小图标
Hexo中大量使用Font Awesome图标,这些图标可以在此处查阅。
修改主题
5. 安装NexT主题
NexT主题有多种安装方法[4]。若不需要修改NexT主题,推荐使用npm
安装包的方式。
npm install hexo-theme-next --verbose
其他安装方式参考[4]。
6. 启用NexT主题
修改Hexo配置文件_config.yml
相关字段为如下:
1 | theme: next |
即可启用NexT主题。
7. 配置NexT主题
主题的配置文件有多个位置,但是推荐使用最新的方法[5]。其余方法要么会修改包,要不可能被覆盖(这些也是网上常见的方法)。
将NexT主题的默认配置文件_config.yml
(一般位于node_modules/hexo-theme-next/_config.yml
)复制到工作目录根目录并改名为_config.next.yml
,注意不要覆盖Hexo配置文件_config.yml
。
cp node_modules/hexo-theme-next/_config.yml _config.next.yml # 参考命令
NexT主题的配置文件_config.next.yml
相关配置信息参考[6]。
常用配置
默认语言选择(影响部分插件选择的语言):
_config.yml 1
language: zh-CN
切换主题方案为Gemini:
_config.next.yml 1
2
3
4#scheme: Muse
#scheme: Mist
#scheme: Pisces
scheme: Gemini
可以运行Hexo服务器查看效果。
内容创作
8. 创建新文章
方法一:通过Hexo创建新文章
运行
hexo new [layout] <title>
即可创建新文章。
其中[layout]
有如下三个选项
布局 | 储存路径 | 说明 |
---|---|---|
post | source/_posts |
一般日志文章 |
page | source |
独立页面 |
draft | source/_drafts |
日志草稿 |
它们的模板在scaffolds/
。
其实创建新文章也可以手动创建,本质是添加.md
文件。
tip
假设要添加的文章标题为《naïve》,则运行
hexo new naïve
会在source/_posts
目录下新建一个名为naïve.md
的文件和一个名为naïve
的目录。例如:
1 | <git-repo> |
在naïve.md
中,通过[too-simple](too-young.png)
即可引用too-young.png
。
tip
文件名可以有非拉丁字符,只要文件系统支持;
文章标题可以和文件名不同,文件名只影响编译后文章网址。
关于独立页面的详细信息,参阅[26]。
方法二:手动创建新文章相关文件
创建新文章本质是添加.md
文件和相应目录。
如方法一所示,在source/_posts
目录下手动添加相应的文件naïve.md
和目录naïve
即可。
Front Matter
每篇文章的开头都有一个“Front Matter”块。例如:
1 | --- |
关于“Front Matter”中的字段,参考[24-25]。
如果一篇文章有更新,设置updated
项会标记该文章更新的时间。
文章置顶
在“Front Matter”块中将sticky
设为100。
1 | --- |
9. 网站目录
目录信息在NexT主题的配置文件_config.next.yml
中配置。post
类型以外的页面的目录需要手动维护。
NexT支持多层目录,详情参考[6]的“Configuring Menu Items”一节。
10. 文章列表
默认情况下,主页上会罗列最新的文章。如果不额外设置,那么这些文章的正文会全部显示在主页上。有两种方法控制显示的内容多寡[27],并将剩余内容用一个阅读全文
按钮替代。
在正文中要切断的地方加入
1
<!-- more -->
该语句前的内容会显示在文章列表内,后面的内容被折叠。
在文章的“Front Matter”块中填写
description
项,1
2
3
4
5---
title: 很长的帖子
...
description: 这是摘要
---主页上即展示
description
,并将整篇文章折叠。
11. 标签、分类和归档页面
标签、分类页面是独立页面,它们的设置参阅[26]中《Adding «Tags» Page》《Adding «Categories» Page》两节。
归档页面是自动创建的页面,它的设置参阅[5]中《Configuring Menu Items》一节。
12. 资源文件
资源文件(如图片、样式表、脚本等)即可以放在全局资源文件夹里,也可以放在文章自己的资源文件夹里。其中后者需要额外设定。
⑴ 全局资源文件夹
在source
下任意位置均可,生成后会复制到对应目录。
例如建立一个目录source/images
,将图片image.jpg
放入,然后可以通过
来引用。
⑵ 文章资源文件夹
除了全局资源文件夹,每个帖子还有一个自己的资源文件夹。该功能默认关闭,需要打开。
Hexo配置文件_config.yml
需要修改以下配置[23]:
1 | post_asset_folder: true |
其中,marked
字段是Hexo默认Markdown转换程序hexo-renderer-marked
插件的配置,详情见后文。
以上配置缺一不可,否则图片地址会错误。
另,修改该配置后缓存可能出问题,建议清除缓存后重新生成,详见此处。
插件的安装与配置
NexT推荐的插件可在[8]和[9]中查看。
注意:有些插件需要从GitHub下载,需要配置代理方可正常安装。
1. 控制首页、归档页、标签页中显示文章数
首页文章数由Hexo配置文件_config.yml
的index_generator
字段决定。具体情况参照Hexo官方文档。
1 | index_generator: |
归档页和标签页的数量由插件hexo-generator-archive
和hexo-generator-tag
控制(新版本NexT似乎已经预装)。安装方法为:
npm install hexo-generator-archive hexo-generator-tag --verbose
在Hexo配置文件_config.yml
追加配置:
1 | # Hexo Generator Archive |
在这两个插件的官方文档中,有介绍各参数的用途,部分已经在上文中提到,在此不再赘述。
2. 默认渲染器设置
Hexo默认渲染器为hexo-renderer-marked
,但是其配置并没有储存在Hexo配置文件_config.yml
中。打开文章资源文件夹需要依赖该插件的设置。
一种设置如下:
1 | # Hexo Renderer Marked |
其各项含义查阅官方文档,在此不再赘述。
3. 其他NexT内置插件
⑴ 公式插件MathJax
显示LateX数学公式。看起来只要将NexT主题的配置文件_config.next.yml
内开关打开即可。
1 | # Math Formulas Render Support |
详细信息参考NexT官方文档相关内容。
⑵ 优化文章加载插件PJAX
PJAX能在切换文章时避免重新加载网页框架,以此提高加载速度。只需要将NexT主题的配置文件_config.next.yml
内开关打开即可。
1 | # Easily enable fast Ajax navigation on your website. |
详细信息参考NexT官方文档相关内容。
⑶ 媒体放大插件Fancybox和Medium Zoom
让媒体(图片、视频等)可以点击放大。其中Medium Zoom只支持图片。这两个插件不能同时启用。
详细信息参考NexT官方文档相关内容。
⑷ 延迟加载图片插件Lazyload
到显示时才加载图片,以便提高效率、降低流量使用。只需要将NexT主题的配置文件_config.next.yml
内开关打开即可。
1 | # Vanilla JavaScript plugin for lazyloading images. |
详细信息参考NexT官方文档相关内容。
⑷ 调整汉英词间隙插件Pangu
自动在汉字和半角英文数字符号之间插入空格。只需要将NexT主题的配置文件_config.next.yml
内开关打开即可。
1 | # Automatically insert whitespace between CJK and half-width characters. |
详细信息参考NexT官方文档相关内容。
⑸ 动画效果插件
效果不明,但是默认配置被设为打开。详细信息参考NexT官方文档相关内容。
⑹ 阅读进度条插件Pace
在显示一个网页加载的进度条。只需要将NexT主题的配置文件_config.next.yml
内开关打开即可。
1 | # Progress bar in the top during page loading. |
在官方网站可以看到各个配置的效果。NexT官方文档中的介绍见此处。
⑺ 背景插件Canvas Ribbon
给网站添加一个随机碎片色块效果的背景,每次鼠标点击会生成一张新的。只需要将NexT主题的配置文件_config.next.yml
内开关打开即可。
1 | # Generate a ribbon in your website with HTML5 canvas. |
需要注意,zIndex
表示画布层,值越小在越后面的层。详情见官方页面。
⑻ 评论插件utterances(仅GitHub)
NexT已经集成了utterances,不需要按照官方页面给出的方法置入评论区。
在GitHub中安装utterances的APP,以便自动给访问提供令牌。可以将安装范围限定于需要使用GitHub Page的仓库。
在NexT主题的配置文件_config.next.yml
中填写各项参数的内容。
1 | # Utterances |
需要注意,repo
指的是作为评论载体的议题页面所在的仓库。
4. 烟花
一个没什么用的鼠标特效,但是包含典型的配置流程。
按照官方页面所提供的信息,安装方法为:
运行
npm install next-theme/hexo-next-fireworks --verbose
在Hexo配置文件_config.yml
加入
1 | # Hexo NexT Fireworks |
启用该插件。
5. Canvas Nest 背景动画
一个同样没什么用的鼠标特效,包含一种典型的js配置流程。
JavaScript来源:canvas-nest.js
官方页面中的安装方法是旧版Hexo采用的,这里采用新方法——
在NexT主题的配置文件_config.next.yml
启用footer.njk
,即将footer
项的注释去掉:
1 | # Define custom file paths. |
仓库中新建或修改该文件source/_data/footer.njk
,增加内容:
1 | <script color="0,0,255" opacity="0.5" zIndex="-1" count="99" src="https://cdn.jsdelivr.net/npm/canvas-nest.js@1/dist/canvas-nest.js"></script> |
上文使用了theme-next
提供的CDN,如果该CDN不能用,则考虑使用某国内的镜像:
1 | <script color="0,0,255" opacity="0.5" zIndex="-1" count="99" src="https://lib.baomitu.com/canvas-nest.js/1.0.1/canvas-nest.js"></script> |
在该脚本的文档中,有介绍各参数的用途,在此不再赘述。
6. 增加作者
在标题下增加一个“合作作者”的项。
按照官方页面信息安装:
npm install theme-next/hexo-next-coauthor --verbose
在NexT主题的配置文件_config.next.yml
(官方没有提)登记作者信息:
1 | # Add some descriptions to your co-authors |
在文章头中加入信息:
1 | title: Hello! NexT Test Site |
作者名字如果是已登记的标识符,则会用nick
字段显示,并且带有链接;否则会直接显示字面量。
其余信息查看官方页面。
7. 本地搜索插件searchdb
一个静态的搜索插件,在生成网站时编制好索引,不需要任何后端。参考NexT官方文档相关内容。
65535. 其余的插件等之后补充
生成和部署
Hexo生成的网站有多种方法部署。
*注:*以下内容主题无关;以下各小标题间并非是简单的顺序或者并列关系。
1. 使用Hexo Server临时部署
第一次使用需要安装hexo-server
。运行(现在似乎Hexo默认安装了,不需要手动安装)
npm install hexo-server --verbose
安装完毕后运行
hexo server
待hexo
打印
1 | INFO Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop. |
时,到该地址可预览网站效果。详情参考[10]。
文档声称该服务器可以实时更新,实测该功能仅限于在Linux系统上将文章源文件实时更新到服务器上。即:限定Linux系统,并且仅修改文章源文件可以被更新,而修改配置表等文件并不会更新。
2. 生成静态文件
运行
hexo generate
完成后在public
目录下会生成网站的静态html。该文件夹的内容可以被GitHub Pages、GitLab Pages和NGINX等服务部署。但是直接在浏览器中打开会缺少样式表。详情参考[11]。
如果遇到结果与预期不符的情况,需要运行
hexo clean
清除缓存后重新生成。
3. 按Hexo配置一键部署
Hexo可以将生成好的静态文件用不同的方式部署到指定位置(一键部署),如通过Git仓库、文件传输等方式。常用的部署方式有Git、Rsync、SFTP等。Git方式适合上传到GitHub Pages、GitLab Pages等代码托管网站;文件传输的方式适合NGINX等方式部署。
要使用某种部署方法,需要安装相应插件。之后在Hexo配置文件_config.yml
的deploy
字段加入相应信息,多个并列子项会依次执行。如
1 | deploy: |
其参数与对应软件对应参数并无区别,详细信息参考[12]。
运行
hexo deploy
即可根据配置部署编译好的网站。
可以同时进行生成和部署,方法为运行
hexo generate --deploy
hexo deploy --generate
二者等价。详细信息参考[11-12]。
注:已知问题:
rsync
同步到所有者非登录用户的路径时会报错(因为rsync
用了-a
参数),但是文件可以更新sftp
指定privateKey
的地方不能使用~
4. 使用NGINX部署
安装NGINX
Ubuntu系统运行[13]
sudo apt-get install nginx
详情略。
配置NGINX
NGINX服务器的配置文件为nginx.conf
(一般在/etc/nginx/nginx.conf
),内容如下
1 | user <user>; |
这个文件中第一行指定了NGINX运行时的用户(以root
启动),需要保证该用户有所需文件的读权限,否则404。
这个文件http
段中声明了要包含/etc/nginx/sites-enabled/
目录下的所有文件,默认的网站配置文件就在这个目录。
浏览该目录可知默认配置文件名default
(当前位于/etc/nginx/sites-enabled/default
),内容如下:
1 | ... |
该文件指定了默认服务器监听的端口80
(http)、网站根目录的位置/var/www/html
以及主页文件名、错误页面文件名等信息。
我们可以根据自己的需求修改root
字段到public
文件夹或者部署的目标目录(不能是Git仓库)。或者干脆新建一个配置文件。
配置文件的详细信息参考[14]。
启动NGINX
有多种方法:
sudo nginx
sudo service nginx start
...
打开配置中指定的端口号检查是否启动成功。
5. 使用docker的NGINX镜像部署
使用nginx:stable
镜像构造纯净环境部署网站,避免各种莫名其妙的问题。
以nginx:1.24.0
举例,该镜像默认的NGINX配置文件在/etc/nginx/nginx.conf
,默认用户是nginx
(uid=101),默认网站配置文件在/etc/nginx/conf.d/default.conf
,网站根目录是/usr/share/nginx/html
。上述信息可以通过以下命令查看:
docker run -it --rm nginx:1.24.0 bash # 创建容器
cat /etc/nginx/nginx.conf # 默认位置
cat /etc/nginx/conf.d/default.conf # 通过nginx.conf查得
因此如果不修改配置文件,可以直接将我们自己的网站public
目录或部署目标目录挂载到容器的对应目录上实现挂载。命令举例如下:
docker run -dit --rm -p 60080:80 -v /run/shm/hexo-html:/usr/share/nginx/html:ro nginx:1.24.0
参数解释
-d: 打印容器ID后后台运行
-it: 启用标准输入输出和终端
--rm: 容器停止后删除容器
-p: 将容器的80端口映射到主机的60080上
-v: 将主机的/run/shm/hexo-html目录映射到容器的/usr/share/nginx/html(覆盖了NGINX默认网页位置)
需要注意的是,因为NGINX镜像的用户为nginx
(101),而主机上一般没有这个用户,因此需要把/run/shm/hexo-html
的权限提前设置好。Docker命令详细信息参考[21]。
6. 通过GitHub Actions部署至GitHub Pages
本方法会将网站源码传到GitHub,然后使用GitHub Actions进行生成,生成的内容提交到gh-pages
分支,最后发布到GitHub Pages。
需要在.github/workflows/pages.yml
中写入配置信息。参考[15-16]中所述进行操作。
需要注意,Hexo配置文件_config.yml
中的url
和root
字段需要进行设置,不能使用默认值。
7. 通过一键部署部署至GitHub Pages
本方法不会将网站源码传到GitHub,而是由Hexo生成静态文件到public
文件夹,自动提交到指定仓库的指定分支,最后发布到GitHub Pages。
参考[15]中所述进行操作。
注意事项同上。
8. 通过GitLab CI部署至GitLab Pages
本方法会将网站源码传到GitHub,然后使用GitLab CI进行生成,生成的内容保存在“作业”内[20],最后发布到GitLab Pages。
需要在.gitlab-ci.yml
中写入配置信息。参考[17-19]中所述进行操作。
本方案没有经过测试,注意事项理应同上。
9. 通过一键部署部署至GitLab Pages
没有试过,理论上是可行的。
NPM包升级
查看当前过期包
npm outdated
检查可升级的包
ncu
更新package.json
到最新版本
ncu -u
安装更新后的包
npm install
参考资料
- Documentation | Hexo;
文档 | Hexo; - Setup | Hexo;
建站 | Hexo; - Configuration | Hexo;
配置 | Hexo; - Getting Started | NexT;
- Configuration | NexT;
- Theme Settings | NexT;
- Writing | Hexo;
写作 | Hexo; - Plugins | NexT;
- Third-party Plugins | NexT;
- Server | Hexo;
服务器 | Hexo; - Generating | Hexo;
生成文件 | Hexo; - One-Command Deployment| Hexo;
部署 | Hexo; - Installing NGINX Open Source | NGINX Documentation;
- Configuring NGINX and NGINX Plus as a Web Server | NGINX Documentation;
- GitHub Pages | Hexo;
在 GitHub Pages 上部署 Hexo | Hexo; - Quickstart for GitHub Pages - GitHub Docs;
GitHub Pages 快速入门 - GitHub 文档; - GitLab Pages | Hexo;
将 Hexo 部署到 GitLab Pages | Hexo; - GitLab Pages | GitLab;
极狐GitLab Pages (FREE ALL) | 极狐GitLab; - Get started with GitLab CI/CD | GitLab;
极狐GitLab CI/CD 入门 (FREE ALL) | 极狐GitLab; - Job artifacts | GitLab;
作业 (FREE ALL) | 极狐GitLab; - Docker run reference | Docker Docs;
- a. xiaosiyu0603/hexo - Docker Image | Docker Hub;
b. xiaosiyu0603/hexo-docker: Dockerfile to build a Hexo development environment based on node.js stable.; - Asset Folders | Hexo;
资源文件夹 | Hexo; - Front-matter | Hexo;
Front-matter | Hexo(中文); - Front Matter | NexT;
- Custom Pages | NexT;
- Post Settings | NexT;
- Hexo NexT 使用 utterances 评论区 | Bambrow's Blog;
相似主题的帖子: