Sa-Token 文档站 VitePress 改造reservedPlugins 备用插件开关机制深度解析【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token导读Sa-Token 新版文档站sa-token-doc-new基于 VitePress 构建并从旧版 Docsify 站点迁移了一批现网曾用的页面增强插件Gitee star 检查、问卷邀请、章节锁、公众号解锁、阅读进度条。为了控制发布风险这些插件被统一收拢到reservedPlugins开关下上线默认全关、按需动态加载。本文将以 备用插件 README 为骨架结合reserved/目录源码与public/static/静态资源讲清这套开关机制的配置方式、每个插件的真实行为以及从 Docsify 迁移到 VitePress 过程中的关键适配点读完即可在自己的文档站中复现同样的插件保险丝设计。一、什么是备用插件设计动机与默认策略原文档开宗明义这些插件是从现网 Docsify 注释插件本地化改装而来上线默认全关。这里的背景是旧站Docsify时代站点通过 is-star-plugin.js、is-fill-in-wj-plugin.js、doc-lock-plugin.js 等脚本实现弹层、章节锁定等运营能力。迁移到 VitePress 后这些能力不再是无条件启用的默认行为而是降级为默认关闭、显式开启的备用选项原因有三发布安全弹层、锁章节等行为属于强干扰型交互默认全开可能影响读者阅读体验关闭状态作为默认基线最稳妥按需加载通过动态import()按开关加载关闭状态下的插件代码不会打进首包见下文bootReserved()的实现迁移可控Docsify 插件钩子hook.beforeEach/doneEach与 VitePress 的路由机制完全不同统一收口到开关后可逐个验证再放开。二、开关配置reservedPlugins与开关总表所有开关集中在reserved目录下的 index.ts 中核心代码为export const reservedPlugins { star: false, // Gitee star 检查弹层 survey: false, // 问卷邀请 docLock: false, // 章节锁 docLockByGzh: false, // 公众号章节锁 progress: false // 顶部阅读进度条 }原文档给出的开关总表如下五个插件一一对应开关原文件行为starstatic/is-star-plugin.jsGitee star 检查弹层surveystatic/is-fill-in-wj-plugin.js问卷邀请docLockstatic/custom-docsify-plugins/doc-lock-plugin.js章节锁docLockByGzhstatic/custom-docsify-plugins/doc-lock-by-gzh-plugin.js公众号章节锁progressstatic/docsify-plugins/progress.update.js顶部阅读进度条对应到当前仓库这些原文件均位于 public/static 目录下包括public/static/is-star-plugin.jsstar 检查public/static/is-fill-in-wj-plugin.js问卷public/static/custom-docsify-plugins/doc-lock-plugin.js与配套样式doc-lock-plugin.css章节锁public/static/custom-docsify-plugins/doc-lock-by-gzh-plugin.js公众号解锁public/static/docsify-plugins/progress.update.js进度条新版已改用 TS 原生实现见下文从源码结构看docLock与docLockByGzh共用同一份doc-lock-plugin.css仅脚本不同因此它们被设计为两个独立开关。三、启用流程改开关 重新构建原文档明确给出启用方法这是本节的可执行步骤务必完整保留开关在同目录index.ts的reservedPlugins。改true后重新npm run docs:build。完整操作路径为编辑 sa-token-doc-new/.vitepress/theme/reserved/index.ts把目标插件对应的开关从false改为true在 sa-token-doc-new 目录执行重新构建npm run docs:build本地预览验证npm run docs:preview对应vitepress preview。构建脚本定义在 package.json 中scripts: { docs:dev: vitepress dev, docs:build: vitepress build, docs:preview: vitepress preview }注意两点适用前提本地开发npm run docs:dev同样会执行bootReserved()因此改完开关后 dev 模式即可观察效果但真正上线以docs:build产物为准环境要求 Node.js 20.11engines字段声明构建时请确保版本满足。四、源码级原理bootReserved()的动态加载机制开关表本身不产生任何副作用真正的工作由 index.ts 中的bootReserved()完成export function bootReserved() { if (reservedPlugins.progress) { import(./progress.ts).then((m) m.startProgress()) } if (reservedPlugins.star) { import(./star.ts).then((m) m.startStarCheck()) } if (reservedPlugins.survey) { import(./survey.ts).then((m) m.startSurvey()) } if (reservedPlugins.docLock) { import(./doc-lock.ts).then((m) m.startDocLock()) } if (reservedPlugins.docLockByGzh) { import(./doc-lock-gzh.ts).then((m) m.startDocLockByGzh()) } }这个实现有两个值得注意的设计点动态import()按需分包每个插件都是一个独立的import(./xxx.ts)关闭状态的插件不会打进首包这正是默认全关在性能上的价值——生产环境不加载任何备用插件的代码。入口在主题钩子中统一触发bootReserved()被 theme/index.ts 的enhanceApp()中调用bootReserved()一行与bootHashScroll()并列说明它属于主题初始化阶段的一部分不依赖具体文档页面。五个插件入口模块均为壳式设计各自只做一件事——把旧脚本/样式挂到页面上或直接以原生 JS 实现功能。下面逐个拆解。4.1progress原生实现顶部阅读进度条与其他四个塞脚本的插件不同进度条在 progress.ts 中直接以原生 DOM 实现不再引用旧版 progress.update.js创建一个position: fixed; top: 0; left: 0的 3px 高度容器内部内嵌一根宽度初始为 0 的进度条进度条颜色取var(--theme-color, #42b983)跟随主题变量缺失时回退到 VitePress 默认绿监听window的scroll事件{ passive: true }优化滚动性能按公式top / remain计算百分比并更新宽度remain scrollHeight - clientHeight当页面不足一屏时宽度强制为 0。这种原生实现的好处是零依赖、无外部脚本请求也无需处理 Docsify 钩子兼容问题。4.2starGitee star 检查弹层star.ts 的逻辑极简——动态往body注入script src/static/is-star-plugin.js真正的检查逻辑全部留在旧脚本 is-star-plugin.js 中。从该脚本源码可以确认它的真实行为非 PC 端不检查document.body.offsetWidth 800时直接return域名白名单location.host ! docDomaindocDomain sa-token.com时不检查检查频率控制通过localStorage.isStarRepo记录上次检查时间间隔allowDisparity 1000 * 60 * 60 * 24 * 30 * 3约 3 个月内不再重复弹层脚本顶部保留了 OAuth 相关的client_id、redirect_uri等配置文件内client_secret已被置为占位符。也就是说启用star开关只是挂上检查脚本是否真正弹层还受设备宽度、域名、时间间隔三层条件约束。4.3survey问卷邀请survey.ts 与star完全同构——注入/static/is-fill-in-wj-plugin.js。问卷逻辑同样封闭在旧脚本内开关只负责挂载。4.4docLock与docLockByGzh章节锁与公众号解锁这两者的入口实现doc-lock.ts 与 doc-lock-gzh.ts均为先挂 CSS 再挂 JS向head注入link relstylesheet href/static/custom-docsify-plugins/doc-lock-plugin.css再向body注入对应的旧脚本doc-lock-plugin.js或doc-lock-by-gzh-plugin.js。从源码注释可以确认锁哪些章节、怎么解锁逻辑全在那份旧脚本里这里只负责挂上去即入口模块不做任何锁定判定完全委托给旧脚本。两个开关共用同一份 CSS因此只需维护一份锁定样式。五、关键适配从 Docsify 路由到 VitePress 路由原文档特别强调了一条迁移要点路径匹配已改成 VitePress 的location.pathname/sso/xxx.html不再用 Docsifyvm.route.path。这解释了为什么旧脚本不能直接原样运行Docsify 插件通过hookvm.route.path感知当前路由如/sso/xxx依赖 Docsify 全局vm实例VitePress 是纯静态站点生成器客户端路由基于location.pathname页面 URL 形如/sso/xxx.html。因此迁移时所有基于路由的判定例如锁定某个章节路径都必须改为读取location.pathname。这与 theme/index.ts 中自定义路由拦截把/use/foo.html与/use/foo视为同一页、静态页整页跳转等是同一套改造思路共同构成了 VitePress 站点对旧站 URL 形态的兼容层。六、资源本地化全部静态文件仓库自持、不走 CDN原文档强调脚本和样式都在本仓库public/static/不走 CDN。从 public/static 目录结构可以验证所有备用插件依赖的脚本、样式连同 Docsify 时代的docsify.min.js、jquery.min.js、layer-v3.1.1、prism等资源全部随仓库分发。这意味着站点不依赖任何第三方 CDN 的可用性离线可构建、可部署入口模块注入的/static/...路径是 VitePress 的public目录约定构建后原样拷贝到产物根目录从源码结构看progress是唯一不依赖任何静态文件的插件——它已完全 TS 化。七、实战小结这套机制能复用什么回到 备用插件 README 本身它其实只用了寥寥数行就定义了一整套可复用的文档站插件管理范式统一开关表一个对象集中声明所有可选增强false为默认安全态动态加载bootReserved()按开关import()关闭即零成本壳式迁移旧逻辑保留为独立脚本新入口只负责挂载最大程度复用已验证代码资源自持脚本样式全部本地化杜绝 CDN 单点路由适配集中化路径判定收敛到location.pathname与 VitePress 约定对齐。如需在当前文档站启用其中任一能力只需改 reserved/index.ts 中对应开关为true并重新npm run docs:build如需为项目新增一个备用插件沿reserved/目录下的五个模块任一模板复制即可注意在bootReserved()中补充对应的动态导入分支并在开关表中登记条目与说明。输出文章【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Sa-Token 文档站 VitePress 改造：reservedPlugins 备用插件开关机制深度解析
Sa-Token 文档站 VitePress 改造reservedPlugins 备用插件开关机制深度解析【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token导读Sa-Token 新版文档站sa-token-doc-new基于 VitePress 构建并从旧版 Docsify 站点迁移了一批现网曾用的页面增强插件Gitee star 检查、问卷邀请、章节锁、公众号解锁、阅读进度条。为了控制发布风险这些插件被统一收拢到reservedPlugins开关下上线默认全关、按需动态加载。本文将以 备用插件 README 为骨架结合reserved/目录源码与public/static/静态资源讲清这套开关机制的配置方式、每个插件的真实行为以及从 Docsify 迁移到 VitePress 过程中的关键适配点读完即可在自己的文档站中复现同样的插件保险丝设计。一、什么是备用插件设计动机与默认策略原文档开宗明义这些插件是从现网 Docsify 注释插件本地化改装而来上线默认全关。这里的背景是旧站Docsify时代站点通过 is-star-plugin.js、is-fill-in-wj-plugin.js、doc-lock-plugin.js 等脚本实现弹层、章节锁定等运营能力。迁移到 VitePress 后这些能力不再是无条件启用的默认行为而是降级为默认关闭、显式开启的备用选项原因有三发布安全弹层、锁章节等行为属于强干扰型交互默认全开可能影响读者阅读体验关闭状态作为默认基线最稳妥按需加载通过动态import()按开关加载关闭状态下的插件代码不会打进首包见下文bootReserved()的实现迁移可控Docsify 插件钩子hook.beforeEach/doneEach与 VitePress 的路由机制完全不同统一收口到开关后可逐个验证再放开。二、开关配置reservedPlugins与开关总表所有开关集中在reserved目录下的 index.ts 中核心代码为export const reservedPlugins { star: false, // Gitee star 检查弹层 survey: false, // 问卷邀请 docLock: false, // 章节锁 docLockByGzh: false, // 公众号章节锁 progress: false // 顶部阅读进度条 }原文档给出的开关总表如下五个插件一一对应开关原文件行为starstatic/is-star-plugin.jsGitee star 检查弹层surveystatic/is-fill-in-wj-plugin.js问卷邀请docLockstatic/custom-docsify-plugins/doc-lock-plugin.js章节锁docLockByGzhstatic/custom-docsify-plugins/doc-lock-by-gzh-plugin.js公众号章节锁progressstatic/docsify-plugins/progress.update.js顶部阅读进度条对应到当前仓库这些原文件均位于 public/static 目录下包括public/static/is-star-plugin.jsstar 检查public/static/is-fill-in-wj-plugin.js问卷public/static/custom-docsify-plugins/doc-lock-plugin.js与配套样式doc-lock-plugin.css章节锁public/static/custom-docsify-plugins/doc-lock-by-gzh-plugin.js公众号解锁public/static/docsify-plugins/progress.update.js进度条新版已改用 TS 原生实现见下文从源码结构看docLock与docLockByGzh共用同一份doc-lock-plugin.css仅脚本不同因此它们被设计为两个独立开关。三、启用流程改开关 重新构建原文档明确给出启用方法这是本节的可执行步骤务必完整保留开关在同目录index.ts的reservedPlugins。改true后重新npm run docs:build。完整操作路径为编辑 sa-token-doc-new/.vitepress/theme/reserved/index.ts把目标插件对应的开关从false改为true在 sa-token-doc-new 目录执行重新构建npm run docs:build本地预览验证npm run docs:preview对应vitepress preview。构建脚本定义在 package.json 中scripts: { docs:dev: vitepress dev, docs:build: vitepress build, docs:preview: vitepress preview }注意两点适用前提本地开发npm run docs:dev同样会执行bootReserved()因此改完开关后 dev 模式即可观察效果但真正上线以docs:build产物为准环境要求 Node.js 20.11engines字段声明构建时请确保版本满足。四、源码级原理bootReserved()的动态加载机制开关表本身不产生任何副作用真正的工作由 index.ts 中的bootReserved()完成export function bootReserved() { if (reservedPlugins.progress) { import(./progress.ts).then((m) m.startProgress()) } if (reservedPlugins.star) { import(./star.ts).then((m) m.startStarCheck()) } if (reservedPlugins.survey) { import(./survey.ts).then((m) m.startSurvey()) } if (reservedPlugins.docLock) { import(./doc-lock.ts).then((m) m.startDocLock()) } if (reservedPlugins.docLockByGzh) { import(./doc-lock-gzh.ts).then((m) m.startDocLockByGzh()) } }这个实现有两个值得注意的设计点动态import()按需分包每个插件都是一个独立的import(./xxx.ts)关闭状态的插件不会打进首包这正是默认全关在性能上的价值——生产环境不加载任何备用插件的代码。入口在主题钩子中统一触发bootReserved()被 theme/index.ts 的enhanceApp()中调用bootReserved()一行与bootHashScroll()并列说明它属于主题初始化阶段的一部分不依赖具体文档页面。五个插件入口模块均为壳式设计各自只做一件事——把旧脚本/样式挂到页面上或直接以原生 JS 实现功能。下面逐个拆解。4.1progress原生实现顶部阅读进度条与其他四个塞脚本的插件不同进度条在 progress.ts 中直接以原生 DOM 实现不再引用旧版 progress.update.js创建一个position: fixed; top: 0; left: 0的 3px 高度容器内部内嵌一根宽度初始为 0 的进度条进度条颜色取var(--theme-color, #42b983)跟随主题变量缺失时回退到 VitePress 默认绿监听window的scroll事件{ passive: true }优化滚动性能按公式top / remain计算百分比并更新宽度remain scrollHeight - clientHeight当页面不足一屏时宽度强制为 0。这种原生实现的好处是零依赖、无外部脚本请求也无需处理 Docsify 钩子兼容问题。4.2starGitee star 检查弹层star.ts 的逻辑极简——动态往body注入script src/static/is-star-plugin.js真正的检查逻辑全部留在旧脚本 is-star-plugin.js 中。从该脚本源码可以确认它的真实行为非 PC 端不检查document.body.offsetWidth 800时直接return域名白名单location.host ! docDomaindocDomain sa-token.com时不检查检查频率控制通过localStorage.isStarRepo记录上次检查时间间隔allowDisparity 1000 * 60 * 60 * 24 * 30 * 3约 3 个月内不再重复弹层脚本顶部保留了 OAuth 相关的client_id、redirect_uri等配置文件内client_secret已被置为占位符。也就是说启用star开关只是挂上检查脚本是否真正弹层还受设备宽度、域名、时间间隔三层条件约束。4.3survey问卷邀请survey.ts 与star完全同构——注入/static/is-fill-in-wj-plugin.js。问卷逻辑同样封闭在旧脚本内开关只负责挂载。4.4docLock与docLockByGzh章节锁与公众号解锁这两者的入口实现doc-lock.ts 与 doc-lock-gzh.ts均为先挂 CSS 再挂 JS向head注入link relstylesheet href/static/custom-docsify-plugins/doc-lock-plugin.css再向body注入对应的旧脚本doc-lock-plugin.js或doc-lock-by-gzh-plugin.js。从源码注释可以确认锁哪些章节、怎么解锁逻辑全在那份旧脚本里这里只负责挂上去即入口模块不做任何锁定判定完全委托给旧脚本。两个开关共用同一份 CSS因此只需维护一份锁定样式。五、关键适配从 Docsify 路由到 VitePress 路由原文档特别强调了一条迁移要点路径匹配已改成 VitePress 的location.pathname/sso/xxx.html不再用 Docsifyvm.route.path。这解释了为什么旧脚本不能直接原样运行Docsify 插件通过hookvm.route.path感知当前路由如/sso/xxx依赖 Docsify 全局vm实例VitePress 是纯静态站点生成器客户端路由基于location.pathname页面 URL 形如/sso/xxx.html。因此迁移时所有基于路由的判定例如锁定某个章节路径都必须改为读取location.pathname。这与 theme/index.ts 中自定义路由拦截把/use/foo.html与/use/foo视为同一页、静态页整页跳转等是同一套改造思路共同构成了 VitePress 站点对旧站 URL 形态的兼容层。六、资源本地化全部静态文件仓库自持、不走 CDN原文档强调脚本和样式都在本仓库public/static/不走 CDN。从 public/static 目录结构可以验证所有备用插件依赖的脚本、样式连同 Docsify 时代的docsify.min.js、jquery.min.js、layer-v3.1.1、prism等资源全部随仓库分发。这意味着站点不依赖任何第三方 CDN 的可用性离线可构建、可部署入口模块注入的/static/...路径是 VitePress 的public目录约定构建后原样拷贝到产物根目录从源码结构看progress是唯一不依赖任何静态文件的插件——它已完全 TS 化。七、实战小结这套机制能复用什么回到 备用插件 README 本身它其实只用了寥寥数行就定义了一整套可复用的文档站插件管理范式统一开关表一个对象集中声明所有可选增强false为默认安全态动态加载bootReserved()按开关import()关闭即零成本壳式迁移旧逻辑保留为独立脚本新入口只负责挂载最大程度复用已验证代码资源自持脚本样式全部本地化杜绝 CDN 单点路由适配集中化路径判定收敛到location.pathname与 VitePress 约定对齐。如需在当前文档站启用其中任一能力只需改 reserved/index.ts 中对应开关为true并重新npm run docs:build如需为项目新增一个备用插件沿reserved/目录下的五个模块任一模板复制即可注意在bootReserved()中补充对应的动态导入分支并在开关表中登记条目与说明。输出文章【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考