给Hexo博客文章/页面加密
这篇文章是公开的,故意不加密码——否则你还没学会怎么解锁,就先被拦在门外了。
本文按“我从来没用过 Hexo 加密插件”的起点来写。你看完应该能独立完成三件事:
- 给某一篇文章加密码;
- 给某个页面加密码;
- 让加密内容不要出现在 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。
加密插件做的是:
- 在生成阶段,把文章正文用密码加密成一串密文;
- 把原文替换成一个锁屏界面;
- 在页面里放一段浏览器脚本;
- 访客输入密码后,浏览器在本地解密并显示正文。
记住这条分界线:作者本机负责加密,访客浏览器负责解密。站点服务器只保存密文和解密脚本。
所以有三个很重要的事实:
- 密码正确与否,是在访客浏览器里判断的;
- 解密用的密钥来自密码,不会明文写在生成后的 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 | encrypt: |
字段解释:
| 字段 | 作用 | 新手怎么理解 |
|---|---|---|
abstract |
文章列表 / 首页摘要处的提示 | “这 article 被锁了”那句话 |
message |
锁屏上的提示 | 密码框上方那句“请输入密码” |
wrong_pass_message |
密码错误提示 | 输错时弹的话 |
wrong_hash_message |
内容校验失败提示 | 密码对但密文和当前版本不匹配时弹 |
theme |
锁屏样式 | default 就够用 |
tags |
标签批量加密规则 | 给带某个标签的文章统一密码 |
tags 这一段是可选的。你如果只想单篇加锁,可以先不写 tags。另外,本站公开教程千万不要用 加密资料 标签,否则会被自动加密。
YAML 有两个新手高频坑:
- 冒号后面必须有空格:
message: 请输入密码,不能写message:请输入密码; - 密码里如果有
#、:、空格等字符,用引号包起来:
1 | password: 'a:b#c 123' |
本文所有示例密码都写成占位文字。不要把本站真实密码写进公开文章。
第 3 步:锁一篇文章
打开任意文章,例如:
1 | source/_posts/2026-11-21-my-secret-post.md |
在文件最顶部的 front-matter 里加一行 password:
1 |
|
这五个字段的关系一定要分清:
| 字段 | 负责什么 | 不写会怎样 |
|---|---|---|
password |
真正触发加密 | 不写就完全不加密 |
secret: true |
让 RSS 模板识别“保密文章” | Atom / RSS 可能泄露标题或摘要 |
indexing: false |
让站内搜索排除 | 搜索结果可能搜到标题 |
sitemap: false |
排除 Google sitemap | 可能被搜索引擎抓到 |
baidusitemap: false |
排除百度 sitemap | 可能被百度抓到 |
只有 password 是加密开关,其余四个是“别让它到处露脸”的辅助开关。
优先级
插件选密码的优先级大致是:
1 | 文章 front-matter 的 password |
也就是说,单篇文章写了 password,就以它为准。
第 4 步:锁一个页面
文章在 source/_posts/,页面通常直接在 source/ 下。本站的产品工时页就是:
1 | source/hours/index.md |
它的 front-matter 写法和文章一样:
1 |
|
生成后访问 /hours/,就会先看到锁屏。
页面和文章在插件眼里差别不大:只要 Hexo 渲染出的数据里有 password,插件就会处理。区别只是文件放在哪里、生成后的 URL 是什么。
第 5 步:标签批量加密
如果你有一批文章都要用同一个密码,不建议每篇都复制 password。可以用标签。
先在 _config.yml 配好:
1 | encrypt: |
然后在文章 front-matter 里加标签:
1 |
|
这样所有带 加密资料 标签的文章都会上锁。
标签加密的一个坑
如果只用标签加密,而没写 password 字段,插件确实会加密正文;但 RSS 模板未必知道它是保密文章。
本站的 templates/atom-safe.xml 里的判断逻辑可以写成伪代码:
1 | if not post.secret and not post.password: |
也就是说,只要文章带了 secret 或 password,就不会进入 Atom / RSS。
所以即使你靠标签加密,也最好同时写:
1 | secret: true |
再次提醒:加密资料 在本站是“加密触发标签”。这篇教程不能带这个标签,否则你点开就会看到锁屏。
第 6 步:别让搜索引擎和站内搜索抓到
加密正文虽然被锁住,但标题、摘要、标签仍可能出现在各种列表里。所以本站额外做了几层处理。
6.1 每篇/每页自己声明
就是前面那四行:
1 | secret: true |
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 | User-agent: * |
注意:robots.txt 只是“请搜索引擎不要抓”的君子协定,不是访问控制。真正不该公开的附件,别放在公开目录里。
第 7 步:重新生成,最容易翻车的一步
改完密码、改完 front-matter,不要只刷新浏览器。Hexo 有缓存,旧密文可能还在。
正确流程:
1 | hexo clean |
或者本项目常用:
1 | hexo c |
生成时要看日志里有没有类似:
1 | hexo-blog-encrypt: encrypting ... |
没看到 encrypting 日志,基本就是没加密成功。常见原因:没装插件、front-matter 没写 password、标签没匹配、YAML 写错、缓存没清。
改密码必须整套重来
如果你把密码从 A 改成 B,旧页面里还是用 A 加密的密文。访客输入 B 当然会提示错误。
这时必须:
1 | hexo clean |
hexo clean 会清掉 public/ 和 db.json。如果你手动改过配置但仍不对,可以确认项目根目录的 db.json 是否被删除后重新生成。
验证生成结果
生成后打开:
1 | public/posts/你的文章.html |
如果能看到:
1 | <div id="hexo-blog-encrypt">...</div> |
说明插件已经接管页面。
也可以在生成目录里搜 hbePass,有结果就对了。
第 8 步:本地预览的坑
本站解锁脚本检查过 WebCrypto 是否可用:
1 | const secure = window.isSecureContext || |
所以本地预览请打开:
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:
- 监听
DOMContentLoaded; - 监听
pjax:complete; - 用
MutationObserver盯着锁屏节点; - 发现
/lib/hbe.js没加载就补加载; - 解密成功后调用主题暴露的同步函数。
主题侧在 themes/chengic/source/js/main.js 暴露了:
1 | window.__fomalTocResync = scrollFnToDo |
解锁脚本在正文出现后再调用它们:
1 | window.__fomalTocResync && window.__fomalTocResync() |
如果你用的不是本站主题,不用照抄这些函数。关键是理解:正文是后插入的,主题初始化要“补跑一次”。
第 10 步:本站做的额外增强
下面这些不是插件自带功能,是本站围绕插件补的体验优化。
10.1 解锁按钮
插件默认只有一个密码框,要靠回车触发。本站通过 source/js/unlock-secret.js 在 .hbe-input 后面插了一个按钮:
1 | // 概念示意 |
doUnlock() 本质是在密码框上合成一个 Enter 键事件,真正的校验仍由插件完成。
10.2 错误弹窗美化
插件原本用 window.alert()。本站临时接管它,把系统灰框换成主题风格弹窗:
1 | const oldAlert = window.alert |
接管 window.alert 是全站级副作用。本站靠文案判断是不是加密错误提示,改插件提示语时要同步检查这段逻辑。
10.3 隐藏“重新上锁”按钮
插件解密成功后会显示一个 Encrypt again 按钮。本站用 source/css/site-inject.css 隐藏了它:
1 | .hbe-button { |
访客如果要在同一台设备上清除记忆,可以清浏览器 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 后,页面局部替换可能导致插件脚本没重新执行。本站做了三层兜底:
pjax:complete时重新初始化解锁脚本;MutationObserver监听新插入的锁屏节点;- 发现
/lib/hbe.js不在 DOM 里就补加载一次。
本站插件注入的脚本本身带 data-pjax,主题 pjax 配置也会重新执行带这个属性的脚本。
第 11 步:没有加密插件时怎么办
这一步专门回答“我还没装插件,能不能学会 / 能不能先凑合”。
11.1 只写 password 没用
如果没装 hexo-blog-encrypt,front-matter 里写:
1 | password: 123456 |
Hexo 只会把它当普通字段存着,不会加密任何内容。生成后的 HTML 里正文还是明文。
所以第一步永远是装插件,或者换别的真正做加密的方案。
11.2 纯前端“遮罩”不是加密
下面这种做法只能叫“藏一下”:
1 | <div id="fake-lock">请输入密码</div> |
因为正文已经在 HTML 里了。访客按 F12 就能看到。
不要用 CSS 模糊、display:none、简单 JS 判断密码来做“加密”。那只是把钥匙挂在门上。
11.3 正确路线只有三条
| 路线 | 适合谁 | 说明 |
|---|---|---|
安装 hexo-blog-encrypt |
绝大多数 Hexo 博主 | 本文主线,10 分钟能搞定 |
| 服务端鉴权 | 真机密、客户资料、付费内容 | 用 Nginx / Cloudflare Access / 自建登录 |
| 不放到公开站 | 极敏感资料 | 存网盘或内网,只放说明 |
11.4 如果暂时不能装插件
你可以先做这些低风险准备:
- 把要保护的内容从公开
source/里挪走; - 在
robots.txt里排除相关目录; - 确认 PDF / NC 附件不在公开路径;
- 等能装插件时再按第 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 |
最后再强调一次
password才是加密开关,其他四个字段只是防止泄露;- 改密码后必须
hexo clean && hexo generate; - 静态站加密不是高安全,别拿它保护真正敏感的东西;
- 附件不会被自动加密;
照着上面走一遍,你就已经超过大多数“只会复制 front-matter”的新手了。剩下的,就是把密码换成你自己的,然后亲手生成、解锁、排错。多看一遍日志,比背十条命令都有用。

