Docusaurus 中实现页面级权限控制的深度解析

背景介绍

在现代文档站点建设中，Docusaurus 作为一款优秀的静态站点生成器，以其出色的 MDX 支持和国际化功能受到开发者青睐。然而，当项目需求涉及页面级权限控制时，Docusaurus 默认的 SPA（单页应用）特性会带来一些安全挑战。

核心问题分析

Docusaurus 的默认行为会带来以下安全考量：

1. SPA 路由接管：首次访问后，React Router 接管导航，服务器无法拦截后续请求
2. 预加载机制：所有页面资源会被提前加载，包括受保护内容
3. 资源暴露风险：即使隐藏了链接，JS 包中的内容仍可能被逆向获取

技术解决方案演进

初始方案：禁用 SPA 特性

最初提出的技术方案是通过配置选项禁用 Docusaurus 的 SPA 特性：

// docusaurus.config.js
{
  disableSpaFeatures: true
}

这种方案会导致：

• 所有导航变为完整页面加载
• 取消预加载和预取功能
• 移除全局资源映射表

实践验证

通过客户端模块可以部分实现这一目标：

import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

window.docusaurus = {
  prefetch: () => false,
  preload: () => false
};

但这种方法存在局限性：

• 无法完全隐藏资源文件路径
• 客户端重定向存在被绕过的风险
• 用户体验下降（失去 SPA 的流畅性）

专家推荐方案：双构建模式

经过深入讨论，技术专家推荐了更优的解决方案——构建两个独立站点：

1. 构建流程：

VARIANT=public docusaurus build --out-dir build/public
VARIANT=private docusaurus build --out-dir build/private

2. 路由控制：

• 使用边缘中间件（如 Vercel Edge Middleware）
• 基于认证状态动态路由请求

import { rewrite } from 'edge-middleware';

export default function middleware(request) {
  const url = new URL(request.url);
  url.pathname = isAuthenticated(request) 
    ? "/private" + url.pathname
    : "/public" + url.pathname;
  return rewrite(url);
}

方案优势分析

1. 安全性保障：

   • 严格隔离公共和私有内容
   • 服务器端完全控制访问权限

2. 用户体验优化：

   • 保留 SPA 的流畅导航
   • 维持客户端状态（如侧边栏展开状态）

3. 部署灵活性：

   • 支持子路径和子域名两种策略
   • 适应各种托管环境

实施建议

1. 内容管理：

   • 使用环境变量控制文档包含/排除
   • 保持单一代码库维护两种变体

2. 路径处理：

   • 避免在构建时设置 baseUrl
   • 依赖中间件处理路径重写

3. 认证集成：

   • 实现可靠的 isAuthenticated 方法
   • 考虑结合现有认证系统

总结

在 Docusaurus 项目中实现细粒度权限控制，双构建配合边缘中间件的方案提供了最佳平衡点。这种方法既满足了安全需求，又保持了 Docusaurus 的核心优势，为类似需求的团队提供了可复用的架构模式。