这篇文章是公开的,故意不加密码——否则你还没学会怎么解锁,就先被拦在门外了。

本文按“我从来没用过 Hexo 加密插件”的起点来写。你看完应该能独立完成三件事:

  1. 给某一篇文章加密码;
  2. 给某个页面加密码;
  3. 让加密内容不要出现在 RSS、站内搜索、Google / 百度 sitemap 里。

不需要另外下载任何文件。核心加密只需要一条 npm install hexo-blog-encrypt --save;插件会在生成时自动把 /lib/hbe.js 和 /css/hbe.style.css 放进 public/。第 10 节的解锁按钮、错误弹窗等属于可选增强,不抄也能正常加密和解锁。

后面还会讲本站实际做的那些“额外增强”:解锁按钮、错误弹窗、pjax 兼容、解密后目录和表格修复、隐藏“重新上锁”按钮等。

先说清楚安全边界:静态博客的“加密”是浏览器端解密。密文和解密脚本都会发到访客浏览器里,所以它适合“挡住随手点开的人”,不适合保护真正敏感的机密。真正重要的附件请放服务端鉴权后面。

阅读路线

如果你赶时间,可以按这个顺序跳:

你想做什么 看哪一节
我完全没装过插件 第 1、2 节
只想锁一篇文章 第 3 节
想锁一个页面,比如 /hours/ 第 4 节
想给一类文章统一密码 第 5 节
不想让搜索引擎收录 第 6 节
改完密码却提示错误 第 7 节
本地预览打不开 / 解锁后布局乱 第 8、9 节
想知道本站做了哪些增强 第 10 节
没有插件怎么办 第 11 节
上线前检查 第 12 节

第 0 步:先搞懂“加密到底发生在哪”

Hexo 是静态站生成器。你写的是 Markdown,Hexo 生成的是一堆 .html。

加密插件做的是:

  1. 在生成阶段,把文章正文用密码加密成一串密文;
  2. 把原文替换成一个锁屏界面;
  3. 在页面里放一段浏览器脚本;
  4. 访客输入密码后,浏览器在本地解密并显示正文。

Hexo 文章加密与解锁流程

记住这条分界线:作者本机负责加密,访客浏览器负责解密。站点服务器只保存密文和解密脚本。

所以有三个很重要的事实:

  • 密码正确与否,是在访客浏览器里判断的;
  • 解密用的密钥来自密码,不会明文写在生成后的 HTML 里;
  • 但如果有人把密文下载下来,理论上可以离线暴力猜密码。

本站当前使用的是 hexo-blog-encrypt 3.1.6。它构建期用 Node 自带 crypto,浏览器期用原生 WebCrypto(PBKDF2 + AES-CBC + HMAC),不依赖 crypto-js、jsencrypt 或外部 CDN。


第 1 步:安装插件

在项目根目录执行:

1
npm install hexo-blog-encrypt --save

本项目 package.json 里已经有:

1
"hexo-blog-encrypt": "^3.1.6"

如果你是全新项目,安装完后 package.json 会多出类似这一行。package-lock.json 会锁具体版本。

装完不用在主题里启用什么额外设置,插件自己会注册 Hexo 的渲染过滤器。


第 2 步:写全局配置

打开项目根目录的 _config.yml,加入或确认已有下面这段:

1
2
3
4
5
6
7
8
9
encrypt:
abstract: 本文内容已加密,需要密码才能查看
message: 请输入密码
wrong_pass_message: 密码不对,请重新输入
wrong_hash_message: 密码正确,但内容可能已更新,仍可查看
theme: default
tags:
- name: 加密资料
password: 换成你自己的分组密码

字段解释:

字段 作用 新手怎么理解
abstract 文章列表 / 首页摘要处的提示 “这 article 被锁了”那句话
message 锁屏上的提示 密码框上方那句“请输入密码”
wrong_pass_message 密码错误提示 输错时弹的话
wrong_hash_message 内容校验失败提示 密码对但密文和当前版本不匹配时弹
theme 锁屏样式 default 就够用
tags 标签批量加密规则 给带某个标签的文章统一密码

tags 这一段是可选的。你如果只想单篇加锁,可以先不写 tags。另外,本站公开教程千万不要用 加密资料 标签,否则会被自动加密。

YAML 有两个新手高频坑:

  1. 冒号后面必须有空格:message: 请输入密码,不能写 message:请输入密码;
  2. 密码里如果有 #、:、空格等字符,用引号包起来:
1
password: 'a:b#c 123'

本文所有示例密码都写成占位文字。不要把本站真实密码写进公开文章。


第 3 步:锁一篇文章

打开任意文章,例如:

1
source/_posts/2026-11-21-my-secret-post.md

在文件最顶部的 front-matter 里加一行 password:

1
2
3
4
5
6
7
8
9
---
title: 一篇被锁住的文章
date: 2026-11-21 10:00:00
password: 换成你自己的文章密码
secret: true
indexing: false
sitemap: false
baidusitemap: false
---

这五个字段的关系一定要分清:

字段 负责什么 不写会怎样
password 真正触发加密 不写就完全不加密
secret: true 让 RSS 模板识别“保密文章” Atom / RSS 可能泄露标题或摘要
indexing: false 让站内搜索排除 搜索结果可能搜到标题
sitemap: false 排除 Google sitemap 可能被搜索引擎抓到
baidusitemap: false 排除百度 sitemap 可能被百度抓到

只有 password 是加密开关,其余四个是“别让它到处露脸”的辅助开关。

优先级

插件选密码的优先级大致是:

1
2
3
文章 front-matter 的 password
> _config.yml 里 encrypt.tags 命中的标签密码
> 没有密码,不加密

也就是说,单篇文章写了 password,就以它为准。


第 4 步:锁一个页面

文章在 source/_posts/,页面通常直接在 source/ 下。本站的产品工时页就是:

1
source/hours/index.md

它的 front-matter 写法和文章一样:

1
2
3
4
5
6
7
8
9
---
title: 产品工时
date: 2026-11-18 10:30:28
password: 换成你自己的页面密码
secret: true
indexing: false
sitemap: false
baidusitemap: false
---

生成后访问 /hours/,就会先看到锁屏。

页面和文章在插件眼里差别不大:只要 Hexo 渲染出的数据里有 password,插件就会处理。区别只是文件放在哪里、生成后的 URL 是什么。


第 5 步:标签批量加密

如果你有一批文章都要用同一个密码,不建议每篇都复制 password。可以用标签。

先在 _config.yml 配好:

1
2
3
4
encrypt:
tags:
- name: 加密资料
password: 换成你自己的分组密码

然后在文章 front-matter 里加标签:

1
2
3
4
5
6
7
8
9
10
---
title: 某篇内部文档
date: 2026-11-21 11:00:00
tags:
- 加密资料
secret: true
indexing: false
sitemap: false
baidusitemap: false
---

这样所有带 加密资料 标签的文章都会上锁。

标签加密的一个坑

如果只用标签加密,而没写 password 字段,插件确实会加密正文;但 RSS 模板未必知道它是保密文章。

本站的 templates/atom-safe.xml 里的判断逻辑可以写成伪代码:

1
2
if not post.secret and not post.password:
输出到 RSS

也就是说,只要文章带了 secret 或 password,就不会进入 Atom / RSS。

所以即使你靠标签加密,也最好同时写:

1
secret: true

再次提醒:加密资料 在本站是“加密触发标签”。这篇教程不能带这个标签,否则你点开就会看到锁屏。


第 6 步:别让搜索引擎和站内搜索抓到

加密正文虽然被锁住,但标题、摘要、标签仍可能出现在各种列表里。所以本站额外做了几层处理。

6.1 每篇/每页自己声明

就是前面那四行:

1
2
3
4
secret: true
indexing: false
sitemap: false
baidusitemap: false

6.2 noindex 脚本

本站有 scripts/noindex-secret.js,它会在生成后的 HTML 里检测加密锁屏特征,然后给页面加上:

1
<meta name="robots" content="noindex, nofollow">

这样搜索引擎看到时就知道“别收录”。

6.3 RSS 模板

templates/atom-safe.xml 会跳过带 secret 或 password 的文章。

6.4 robots.txt

本站 source/robots.txt 里还有:

1
2
User-agent: *
Disallow: /work/

注意:robots.txt 只是“请搜索引擎不要抓”的君子协定,不是访问控制。真正不该公开的附件,别放在公开目录里。


第 7 步:重新生成,最容易翻车的一步

改完密码、改完 front-matter,不要只刷新浏览器。Hexo 有缓存,旧密文可能还在。

正确流程:

1
2
hexo clean
hexo generate

或者本项目常用:

1
2
hexo c
hexo g

生成时要看日志里有没有类似:

1
hexo-blog-encrypt: encrypting ...

没看到 encrypting 日志,基本就是没加密成功。常见原因:没装插件、front-matter 没写 password、标签没匹配、YAML 写错、缓存没清。

改密码必须整套重来

如果你把密码从 A 改成 B,旧页面里还是用 A 加密的密文。访客输入 B 当然会提示错误。

这时必须:

1
2
hexo clean
hexo generate

hexo clean 会清掉 public/ 和 db.json。如果你手动改过配置但仍不对,可以确认项目根目录的 db.json 是否被删除后重新生成。

验证生成结果

生成后打开:

1
public/posts/你的文章.html

如果能看到:

1
2
3
4
<div id="hexo-blog-encrypt">...</div>
<input id="hbePass" ...>
<script data-pjax src="/lib/hbe.js"></script>
<link href="/css/hbe.style.css" ...>

说明插件已经接管页面。

也可以在生成目录里搜 hbePass,有结果就对了。


第 8 步:本地预览的坑

本站解锁脚本检查过 WebCrypto 是否可用:

1
2
3
const secure = window.isSecureContext ||
location.hostname === 'localhost' ||
location.hostname === '127.0.0.1'

所以本地预览请打开:

1
http://localhost:4444/你的文章.html

不要直接用:

1
http://192.168.1.23:4444/

局域网 IP 属于非安全上下文,浏览器可能禁用 crypto.subtle,解锁会失败。

如果线上站点没配 HTTPS,也会遇到同样问题。正式站请务必上 HTTPS。


第 9 步:解锁后目录、表格、滚动乱掉怎么办

这是 pjax 主题特别容易遇到的问题。

加密文章的正文不是页面加载时就存在的,而是访客输入密码后才插入 DOM。主题的目录生成、表格包装、滚动监听通常在页面加载时就跑完了,等正文出现时,它们已经“错过”了。

本站的表现曾经是:

  • 目录空白;
  • 表格没有圆角边框;
  • 目录高亮不跟随滚动;
  • pjax 进入文章后插件脚本没重新执行。

本站的解决方式在 source/js/unlock-secret.js:

  1. 监听 DOMContentLoaded;
  2. 监听 pjax:complete;
  3. 用 MutationObserver 盯着锁屏节点;
  4. 发现 /lib/hbe.js 没加载就补加载;
  5. 解密成功后调用主题暴露的同步函数。

主题侧在 themes/chengic/source/js/main.js 暴露了:

1
2
window.__fomalTocResync = scrollFnToDo
window.__fomalScrollResync = scrollFn

解锁脚本在正文出现后再调用它们:

1
2
window.__fomalTocResync && window.__fomalTocResync()
window.__fomalScrollResync && window.__fomalScrollResync()

如果你用的不是本站主题,不用照抄这些函数。关键是理解:正文是后插入的,主题初始化要“补跑一次”。


第 10 步:本站做的额外增强

下面这些不是插件自带功能,是本站围绕插件补的体验优化。

10.1 解锁按钮

插件默认只有一个密码框,要靠回车触发。本站通过 source/js/unlock-secret.js 在 .hbe-input 后面插了一个按钮:

1
2
3
4
5
// 概念示意
const btn = document.createElement('button')
btn.className = 'hbe-unlock-btn'
btn.textContent = '解锁'
btn.addEventListener('click', doUnlock)

doUnlock() 本质是在密码框上合成一个 Enter 键事件,真正的校验仍由插件完成。

10.2 错误弹窗美化

插件原本用 window.alert()。本站临时接管它,把系统灰框换成主题风格弹窗:

1
2
3
4
const oldAlert = window.alert
window.alert = function (msg) {
// 去重后显示自定义 #hbeModal
}

接管 window.alert 是全站级副作用。本站靠文案判断是不是加密错误提示,改插件提示语时要同步检查这段逻辑。

10.3 隐藏“重新上锁”按钮

插件解密成功后会显示一个 Encrypt again 按钮。本站用 source/css/site-inject.css 隐藏了它:

1
2
3
.hbe-button {
display: none !important;
}

访客如果要在同一台设备上清除记忆,可以清浏览器 localStorage:

1
键名:hexo-blog-encrypt:#<页面路径>

例如:

1
hexo-blog-encrypt:#/posts/hexo-encrypt-guide.html

插件记住的不是明文密码,而是推导后的 AES/HMAC 密钥和 iv。但从“这台浏览器能继续看”这个结果看,效果类似记住登录状态。

10.4 脚本注入与缓存版本

本站把解锁脚本放在 _config.chengic.yml 的 inject.bottom 里:

1
- <script defer src="/js/unlock-secret.js?v=20261121"></script>

改了脚本内容后,记得把 ?v= 后面的版本号改掉,并重启 hexo server,否则浏览器可能继续用缓存。

站点样式也是同理:

1
- <link rel="stylesheet" href="/css/site-inject.css?v=20261121">

10.5 pjax 兜底

主题开启 pjax 后,页面局部替换可能导致插件脚本没重新执行。本站做了三层兜底:

  1. pjax:complete 时重新初始化解锁脚本;
  2. MutationObserver 监听新插入的锁屏节点;
  3. 发现 /lib/hbe.js 不在 DOM 里就补加载一次。

本站插件注入的脚本本身带 data-pjax,主题 pjax 配置也会重新执行带这个属性的脚本。


第 11 步:没有加密插件时怎么办

这一步专门回答“我还没装插件,能不能学会 / 能不能先凑合”。

11.1 只写 password 没用

如果没装 hexo-blog-encrypt,front-matter 里写:

1
password: 123456

Hexo 只会把它当普通字段存着,不会加密任何内容。生成后的 HTML 里正文还是明文。

所以第一步永远是装插件,或者换别的真正做加密的方案。

11.2 纯前端“遮罩”不是加密

下面这种做法只能叫“藏一下”:

1
2
<div id="fake-lock">请输入密码</div>
<div id="fake-content" style="display:none">正文</div>

因为正文已经在 HTML 里了。访客按 F12 就能看到。

不要用 CSS 模糊、display:none、简单 JS 判断密码来做“加密”。那只是把钥匙挂在门上。

11.3 正确路线只有三条

路线 适合谁 说明
安装 hexo-blog-encrypt 绝大多数 Hexo 博主 本文主线,10 分钟能搞定
服务端鉴权 真机密、客户资料、付费内容 用 Nginx / Cloudflare Access / 自建登录
不放到公开站 极敏感资料 存网盘或内网,只放说明

11.4 如果暂时不能装插件

你可以先做这些低风险准备:

  1. 把要保护的内容从公开 source/ 里挪走;
  2. 在 robots.txt 里排除相关目录;
  3. 确认 PDF / NC 附件不在公开路径;
  4. 等能装插件时再按第 1~7 步补上。

但不要自欺欺人地认为“前端遮住了就安全”。


第 12 步:上线前检查清单

每次发布加密内容前,按这个表过一遍:

  • [ ] 已安装 hexo-blog-encrypt;
  • [ ] _config.yml 的 encrypt 段配置正确;
  • [ ] 文章或页面 front-matter 写了 password;
  • [ ] 同时写了 secret/indexing/sitemap/baidusitemap: false;
  • [ ] 密码里有特殊字符时已加引号;
  • [ ] 没有把真实密码写进公开文章或注释;
  • [ ] 执行了 hexo clean && hexo generate;
  • [ ] 日志里看到 hexo-blog-encrypt: encrypting ...;
  • [ ] 生成后的 HTML 里有 hbePass;
  • [ ] 用 localhost 或 HTTPS 打开测试;
  • [ ] 输错密码提示正确;
  • [ ] 输对密码正文正常显示;
  • [ ] 目录、表格、滚动高亮正常;
  • [ ] public/atom.xml 里没有该文章标题;
  • [ ] public/search.xml、sitemap.xml、baidusitemap.xml 里没有该文章;
  • [ ] 附件直链不能直接打开;
  • [ ] 修改过 inject 资源后 ?v= 版本号已更新。

常见问题对照表

现象 最可能原因 怎么查
页面完全没锁 没装插件 / 没写 password 看生成日志有没有 encrypting
提示密码错误 旧密文配新密码 hexo clean && hexo generate
提示“密码正确但内容可能已更新” HMAC 对不上 重新生成,确认没有手改 public/
本地解锁失败 不是 HTTPS / localhost 换 http://localhost:4444
pjax 进入后没锁屏 插件脚本没重跑 检查 data-pjax 和主题 pjax 配置
解锁后目录空白 目录生成早于正文插入 补一次目录同步
表格没样式 表格包装早于正文插入 补一次表格包装
搜索还能搜到标题 没写 indexing: false 检查 front-matter 和 search.xml
RSS 泄露 没写 secret: true 检查 atom.xml 和模板
改了没生效 缓存 升 ?v=、强刷、重启 server
访客无法重新上锁 本站隐藏了 Encrypt again 清 localStorage

最后再强调一次

  1. password 才是加密开关,其他四个字段只是防止泄露;
  2. 改密码后必须 hexo clean && hexo generate;
  3. 静态站加密不是高安全,别拿它保护真正敏感的东西;
  4. 附件不会被自动加密;

照着上面走一遍,你就已经超过大多数“只会复制 front-matter”的新手了。剩下的,就是把密码换成你自己的,然后亲手生成、解锁、排错。多看一遍日志,比背十条命令都有用。