vuepress-plugin-encrypt 内容加密插件使用文档

一个 VuePress 插件，是一个专为 VuePress 2.x 开发的内容加密插件，可以为您的文档或博客提供页面级别的密码保护和内容块加密功能

声明

[!CAUTION] 该文档由 AI 自动生成，如有问题请反馈

该插件代码提取自 vuepress-theme-hope 内置加密组件，在其基础上添加 CLI 加密/解密功能

请不要使用该加密功能用于任何敏感、机密的文章与档案，或是使用不当，造成的后果请你自负，本插件作者和贡献者对此不承担任何责任。插件仅供学习交流使用。

功能

• [x] CLI命令实现内容加密
• [x] 路由加密
• [x] 自定义密码组
• [ ] 自定义记住状态时长
• [ ] 自定义验证界面

特性

• 📄 页面加密 - 为特定路径的页面设置密码保护
• 📝 内容加密 - 在 Markdown 中为特定内容块设置密码保护
• 🔑 全局密码 - 设置管理员密码，可以解锁所有加密内容
• 🌐 多语言支持 - 支持多语言配置
• 🎨 主题集成 - 与 VuePress 主题完美集成
• ~~🚀 Vite 构建 - 使用 Vite 进行快速构建~~

工作模式

• 内容加密模式

  • 普通模式：不改变原始内容，加密渲染内容

    （该模式方便修改，但是如果是公开仓库部署，内容还是会暴露）

  • 严格模式：加密原始内容

    （该模式不方便修改，每次修改完需要重新加密，但即使是公开仓库，内容不会暴露）

• 路由加密模式（该模式如果是公开仓库部署，内容还是会暴露）

安装

# npm
npm install vuepress-plugin-encrypt

# yarn
yarn add vuepress-plugin-encrypt

# pnpm
pnpm add vuepress-plugin-encrypt

工作原理

内容加密模式（普通）

Markdwon文档 -> markdown-it解析渲染成html -> 加密html -> cache缓存加密内容 -> 通过plugin解密html -> 在页面中添加解密后的html

内容加密模式（严格）

Markdwon文档 -> build -> 加密原始内容 -> plugin解密原始内容 -> markdown-it解析渲染成html

路由加密模式

访问页面 -> 拦截路由 -> 验证密码 -> 释放路由 -> 显示页面

基本用法

在 VuePress 配置文件中添加插件：

import { defineUserConfig } from 'vuepress'
import { encryptPlugin } from 'vuepress-plugin-encrypt'

export default defineUserConfig({
  plugins: [
    encryptPlugin({
      // 插件配置选项
      global: false,  // 是否启用全局加密
      admin: {
        password: 'admin',  // 管理员密码
        hint: '请输入管理员密码',  // 密码提示
      },
      config: {
        '/guide/': {  // 特定路径加密
          password: 'guide',
          hint: '请输入指南密码',
        }
      }
    })
  ]
})

🔐 CLI 命令行 - AES 加密

插件提供了命令行工具，使用 AES ，用于批量加密/解密Markdown文件

CLI 工具用于加密/解密内容

Options:
  -V, --version                 output the version number
  -h, --help                    display help for command

Commands:
  encrypt [options] <paths...>  加密 Markdown 文件 -p 加密密码
  decrypt [options] <paths...>  解密 Markdown 文件 -p 解密密码
  help [command]                display help for command

通过 npm scripts 调用（推荐）

在 package.json 中添加

{
  "scripts": {
    "encrypt": "vp-encrypt encrypt",
    "decrypt": "vp-encrypt decrypt"
  }
}

然后运行加密/解密

npm run encrypt -- <加密文件 or 文件夹> -p <加密密码>
npm run decrypt -- <解密文件 or 文件夹> -p <解密密码>

或者使用 npx 直接运行

npx vp-encrypt [options]

🌰举个栗子

# 加密单个文件
npx vp-encrypt encrypt ./docs/secret.md -p mypassword
# 加密整个目录
npx vp-encrypt encrypt ./docs/secret.md -p mypassword

# 解密
npx vp-encrypt decrypt ./docs/secret.md -p mypassword

📂加密案例

# 页面标题

这是公开内容，任何人都可以看到。

::: encrypt token=密码123
这是加密内容，只有输入正确密码才可见。
:::

这又是公开内容。

配置详解

全局配置

encryptPlugin({
  // 是否开启全局加密（所有页面都需要密码访问）
  global: false,
  
  // 管理员配置，管理员密码可以解锁所有加密内容
  admin: {
    password: 'admin',  // 密码
    hint: '请输入管理员密码',  // 提示文本
  },
  
  // 密码记忆选项
  remember: {
    enable: true,  // 是否启用密码记忆功能
    expire: 7,     // 密码过期时间（天）
  },
  
  // 路径加密配置
  config: {
    '/guide/': {  // 路径匹配
      password: 'guide',  // 密码
      hint: '请输入密码查看指南',  // 提示文本
    },
    '/api/': {
      passwords: ['api123', 'backup123'],  # 密码组
      hint: 'API文档密码（可尝试备份密码）',
    }
  },
  
  // 多语言配置
  locale: {
    '/': {
      placeholder: '请输入密码',
      remember: '记住密码',
      errorHint: '密码错误',
    },
    'zh-CN': {
      placeholder: '请输入密码',
      remember: '记住密码',
      errorHint: '密码错误',
    },
    'en': {
      placeholder: 'Please enter the password',
      remember: 'Remember password',
      errorHint: 'Incorrect password',
    }
  },
  
  // 组件替换配置（与其他主题集成时使用）
  replaceComponent: {
    encrypt: "@theme-hope/modules/encrypt/components/GlobalEncrypt",
    globalEncrypt: "@theme-hope/modules/encrypt/components/GlobalEncrypt"
  }
})

自定义样式配置

支持自定义加密框样式，优先级：用户主题变量 > 插件配置 > 插件默认值：

encryptPlugin({
  config: {
    "/chit-chat/demo": "zenghr",
  },
  // 可选：自定义样式（不配置则使用默认值）
  style: {
    colorBg: "#f9fafb",          // 加密框背景色
    colorAccent: "#4f46e5",      // 按钮/边框主色
    colorBorder: "#d1d5db",      // 边框色
    colorShadow: "0 4px 20px rgba(0,0,0,0.1)", // 阴影
    colorText: "#213547",        // 文本色
    colorTextMute: "#888888",    // 次要文本色（如"记住密码"）
  },
})

与主题集成

如果您使用的是 VuePress Theme Hope 支持加密功能的主题，可以不用配置，插件默认集成 VuePress Theme Hope

注册组件 Component 集成

插件默认注册两个全局组件

LocalEncrypt 和 GlobalEncrypt

LocalEncrypt 组件负责 路由加密，你可以在你的主题布局组件中添加该组件，实现加载加密功能

<Layout>
    <HomePage>
    	<LocalEncrypt>
            <NormalPage />
        </LocalEncrypt>
    </HomePage>
</Layout>

GlobalEncrypt 组件负责 全局加密，你可以在你的主题布局组件中添加该组件，实现加载加密功能

<Layout>
    <GlobalEncrypt>
    	<HomePage />
    </GlobalEncrypt>
</Layout>

别名方式集成

如果是其他支持加密功能的主题，你可以使用别名替换成该组件，配置如下

encryptPlugin({
  replaceComponent: {
    encrypt: "@theme-hope/modules/encrypt/components/LocalEncrypt",
    globalEncrypt: "@theme-hope/modules/encrypt/components/GlobalEncrypt"
  }
})

常见问题解答

加密模式如何选择？

• 使用strict模式保护敏感技术文档
• 使用normal模式保护普通博客内容
• 两种模式可混合使用

密码无法记住

确保启用了记住密码功能，并检查浏览器是否允许保存Cookie：

encryptPlugin({
  remember: {
    enable: true,
    expire: 7  // 7天过期
  }
})

和其他插件冲突

如果与其他插件发生冲突，尝试调整插件的加载顺序：

plugins: [
  // 先加载其他插件
  otherPlugin(),
  // 最后加载加密插件
  encryptPlugin(options)
]

加密后无法搜索内容

加密内容默认对搜索引擎隐藏，这是预期行为。如果需要索引加密内容，请使用非严格模式的内容块加密。

~~❌️ 俺不中嘞~~

~~vite 编译后 出现 /* empty css */ 问题，俺不中了 😭 就这样了吧不解决了~~

import "./styles/index.scss"
# 编译后
/* empty css */

~~最后使用 JS 强制注入CSS字符串到页面中~~

~~相同的问题 Why does Vite sometimes replace my CSS imports with /* empty css */~~

~~修改为 TSC 打包~~

开发与贡献

欢迎贡献代码或提交问题：

1. Fork 仓库
2. 克隆到本地：git clone https://github.com/yourusername/vuepress-plugin-encrypt.git
3. 安装依赖：npm install
4. 运行开发服务器：npm run dev
5. 构建：npm run build

兼容性说明

• 支持 VuePress 2.x
• 支持主流浏览器的最新两个版本
• 支持 Node.js 16.0.0 及以上版本

许可证

MIT

希望此文档能帮助您快速上手使用 vuepress-plugin-encrypt 插件。如有更多问题，请参考GitHub仓库的Issues或提交新的Issue。