安装与主题配置

本文介绍如何从零搭建一个使用 matery 主题的 Hexo 站点，并完成基础配置。每一步都按「输出 → 对应命令」给出：先看这一步会得到什么，再照抄命令。

1. 创建 Hexo 站点

输出：终端先是 INFO Cloning hexo-starter ...，随后 INFO Install dependencies，结束时打印 INFO Start blogging with Hexo!。当前目录多出 my-blog/，里面有 _config.yml（站点配置）、source/（你写的内容）、themes/（主题，此时只有 landscape）、package.json。

对应命令：

hexo init my-blog
cd my-blog
npm install

hexo init 会自动克隆 hexo-starter 并安装依赖。完成后目录内已包含 _config.yml（站点配置）、source/（内容）、themes/（主题）等基础结构。

2. 安装 matery 主题

输出：themes/matery/ 出现 layout/、source/、scripts/、_config.yml 等目录与文件，git clone 打印 done.。此时主题已就位但尚未启用——要等 §3 把 theme 改成 matery 才生效。

对应命令：

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

本博客使用的是深度定制版 matery（功能远超上游），以 git 子模块方式管理：

git submodule add ssh://git@git.17lai.online:222/work/matery.git themes/matery

输出：终端打印 Cloning into 'themes/matery'...，并在根目录生成 .gitmodules 记录子模块地址。

定制版与上游不兼容，直接替换为上游原版会丢失大量功能，请勿混用。

3. 根 _config.yml 基础配置

输出：hexo server 重启后，浏览器标签页标题变成「夜法之书」，页头副标题显示「深度思考，深入生活」，页面底色/结构换成 matery 的样式（而不是 landscape 默认皮肤）——说明主题与站点信息都已生效。

对应命令：编辑站点根目录 _config.yml，保存后重启预览：

hexo server

# 启用 matery 主题
theme: matery

# 站点语言（matery 中文界面）
language: zh-CN

# 站点基本信息
title: 夜法之书
subtitle: 深度思考，深入生活
description: 个人独立技术博客
author: appotry

主题自身的详细配置在 themes/matery/_config.yml 中（本博客约 3000 行，含菜单、评论、CDN、特效等）。CI 构建时它会被 userConfig/_config.tmp.yml 模板覆盖，所以日常开发改主题配置请改模板文件。

4. 创建必要页面

matery 主题的菜单依赖若干独立页面，用 hexo new page 创建。

输出：终端逐条打印 INFO Created: ~/my-blog/source/about/index.md 等，source/ 下多出 about/、tags/、categories/、friends/、galleries/ 五个目录，每个目录一个 index.md。新建的页面不会自动出现在菜单里，还要在主题配置的 menu 段登记。

对应命令：

hexo new page about
hexo new page tags
hexo new page categories
hexo new page friends
hexo new page galleries

hexo new page 生成的文件只有 title 和 date，必须手动补充 layout 字段（否则页面不会按对应布局渲染）。补完 layout 后重新生成，访问 /about/ 就能看到"关于"版式，而不是一篇文章的版式。

单个相册页用 hexo new gallery <名称> 创建（layout: gallery，加密相册可在 front-matter 加 password）。

输出：终端打印 INFO Created: ~/my-blog/source/galleries/<名称>/index.md，该目录下可直接放照片。

对应命令：

hexo new gallery <名称>

5. 安装关键依赖

输出：npm install 结束后终端打印 added N packages（N 随依赖树变化），node_modules/ 里出现对应包；若某个包缺失，构建时会报 Cannot find module 'hexo-renderer-xxx'。

对应命令：把下表依赖加入 package.json 后执行：

npm install

下面是本博客使用到的核心依赖及其用途：

Markdown 渲染增强插件

hexo-renderer-markdown-it 与以下 markdown-it 插件配合，获得丰富的写作语法：

• markdown-it-mathjax3：$...$ 行内 / $$...$$ 块级数学公式
• markdown-it-mermaid：Mermaid 图表（配合 front-matter mermaid: true）
• markdown-it-emoji、markdown-it-footnote、markdown-it-task-checkbox
• markdown-it-container、markdown-it-admon：提示块 / 便签
• markdown-it-ins、markdown-it-mark、markdown-it-sub、markdown-it-sup：文字增强
• markdown-it-multimd-table：增强表格（合并单元格等）

输出：写一段 $E=mc^2$ 与 ```mermaid 代码块后重新生成，页面上分别渲染成公式与流程图；若只显示原始源码，说明对应插件没装上。

对应命令：

hexo clean && hexo generate

文章加密

文章加密由自研 HBE v4 体系提供（2026-08-09 起替代 hexo-blog-encrypt 插件，AES-256-GCM + PBKDF2，主题配置（模板 userConfig/_config.tmp.yml）的 encrypt: 段配置）：

输出：打开带密码的文章时，正文显示为遮罩 + 密码输入框；输入正确密码后正文解密显示。配置未生效时文章仍以明文直接展示。

对应命令：在主题配置（模板）写入 encrypt 段后重新构建：

hexo clean && hexo generate

encrypt:
  enable: true
  tags:
    - {name: 私人, password: "你的密码"}

加密方式：front-matter password（整篇）/ {% encrypt %} tag（片段）/ {wiki}-sidebar.yml 的 encrypt_password（wiki 整体）。详见「布局与页面」篇 §8。

• 按标签加密：文章带加密标签即自动加密
• 按文章加密：front-matter 写 password: "你的密码"（scaffold 中为 SHA256 形式）

6. 本地预览与验证

输出：先看到 INFO Generated: index.html 等一串生成日志（末尾 Files generated in x.xs），随后 Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.。浏览器打开首页能看到轮播/文章卡片，/tags/、/categories/、/about/ 各有对应版式，即验证通过。

对应命令：

hexo clean && hexo generate   # 或 npm run build
hexo server                   # http://localhost:4000/

打开 http://localhost:4000/ 检查首页、标签页、分类页、关于页等是否正常。确认无误后即可通过 hexo deploy 或推送到 GitHub 由 Vercel 构建上线。

输出：hexo deploy 打印 INFO Deploy done: git，托管平台开始构建。

对应命令：

hexo deploy

排障提示：修改配置/模板后页面不生效，先 hexo clean 再 hexo generate；修改 source/_data/*.yml 数据文件后需删除 db.json 再生成。

下一步

• 目录结构与内容管理：文件布局、写作流程、front-matter 速查