安装与主题配置

本文介绍如何从零搭建一个使用 matery 主题的 Hexo 站点，并完成基础配置。

1. 创建 Hexo 站点

hexo init my-blog
cd my-blog
npm install

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

2. 安装 matery 主题

将主题克隆到 themes/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
定制版与上游不兼容，直接替换为上游原版会丢失大量功能，请勿混用。

3. 根 _config.yml 基础配置

编辑站点根目录 _config.yml：

# 启用 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 创建：

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 字段（否则页面不会按对应布局渲染）：

页面	文件	front-matter 要点
关于	`source/about/index.md`	`layout: about`
标签	`source/tags/index.md`	`layout: tags`
分类	`source/categories/index.md`	`layout: categories`
友链	`source/friends/index.md`	`layout: friends`，数据在 `source/_data/friends.yml`
相册首页	`source/galleries/index.md`	`layout: galleries`，数据在 `source/_data/galleries.yml`

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

5. 安装关键依赖

将以下依赖加入 package.json 并 npm install。下面是本博客使用到的核心依赖及其用途：

依赖	用途
`hexo-renderer-markdown-it`	Markdown 渲染引擎（替代默认 marked），支持数学公式、Mermaid、emoji、脚注等大量插件
`hexo-renderer-ejs`	渲染主题的 EJS 模板
`hexo-renderer-stylus`	将主题 `.styl` 样式编译为 CSS
`hexo-abbrlink`	为文章生成短链接永久链接（配合 `permalink: posts/:abbrlink/`）
`hexo-deployer-git`	通过 Git 部署（`hexo deploy` 推送 GitHub 等）
`hexo-generator-sitemap` / `hexo-generator-baidu-sitemap`	生成站点地图（Google / 百度）
`hexo-minify`	构建时压缩 JS/CSS/HTML
`hexo-feed`	输出 RSS / Atom / JSON Feed
`hexo-wordcount`	文章字数统计与阅读时长
`hexo-admin`	提供 `/admin` 可视化后台（需认证）

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：增强表格（合并单元格等）

文章加密

文章加密由 hexo-blog-encrypt 体系提供（本主题内置兼容实现，_config.yml 的 encrypt: 段配置）：

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

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

6. 本地预览与验证

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

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

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

下一步

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