Next.js 16 MDX 安全防护与鲁棒性：纵深防御实战指南

<Callout type="info">
  这是一段说明，内含 <script>alert('xss')</script>
</Callout>

// ❌ 无效防护：MDX v3 不会查找 script 组件
useMDXComponents({
  script: () => null, // 永远不会被调用
});

// ❌ Turbopack 报错：options not serializable
import { myPlugin } from "./lib/my-plugin";
rehypePlugins: [myPlugin];
 
// ✅ 正确：使用 npm 包名或绝对路径字符串
rehypePlugins: ["rehype-slug"];
rehypePlugins: [path.join(process.cwd(), "lib", "my-plugin.cjs")];

// lib/rehype-sanitize-mdx.cjs
const DANGEROUS_TAGS = new Set(["script", "iframe", "object", "embed", "applet", "base", "style"]);
 
function rehypeSanitizeMdx() {
  return (tree) => {
    sanitizeNode(tree);
  };
}
 
function sanitizeNode(node) {
  if (!node.children) return;
  // 过滤 HAST element 和 MDX JSX element
  node.children = node.children.filter((child) => {
    if (child.type === "element" && DANGEROUS_TAGS.has(child.tagName)) return false;
    if (child.type === "mdxJsxFlowElement" && DANGEROUS_TAGS.has(child.name)) return false;
    return true;
  });
  // 递归 + 清洗事件处理器属性
  for (const child of node.children) {
    sanitizeNode(child);
  }
}

// next.config.ts
import path from "node:path";
rehypePlugins: [
  path.join(process.cwd(), "lib", "rehype-sanitize-mdx.cjs"),
  "rehype-slug",
  // ...
];

const DANGEROUS_URL_PATTERN = /^\s*(javascript|vbscript|data\s*:\s*text\/html)/i;
 
// 在 a 标签组件覆盖中
if (DANGEROUS_URL_PATTERN.test(href)) {
  return <span className="line-through">Blocked: unsafe URL</span>;
}

wrapper: ({ children }) => <>{sanitizeReactTree(children)}</>,

script-src 'self' 'unsafe-inline';  // 移除 'unsafe-eval'
frame-src 'none';                    // 阻止所有 iframe
child-src 'none';                    // 阻止子文档加载
object-src 'none';                   // 阻止插件
frame-ancestors 'none';              // 阻止被嵌入

The tag <foo> is unrecognized in this browser.
If you meant to render a React component, start its name with an uppercase letter.

// 有效 HTML 元素白名单（节选）
const VALID_HTML_ELEMENTS = new Set([
  "div",
  "span",
  "p",
  "a",
  "img",
  "br",
  "hr",
  "h1",
  "h2",
  "h3",
  "h4",
  "h5",
  "h6",
  "ul",
  "ol",
  "li",
  "table",
  "tr",
  "td",
  "th",
  "svg",
  "path",
  "g",
  "circle",
  "rect",
  // ...完整列表包含 100+ 合法元素
]);
 
// 在 AST 遍历中
if (!VALID_HTML_ELEMENTS.has(child.tagName)) {
  child.properties["data-original-tag"] = child.tagName;
  child.tagName = "span"; // 安全降级
}

/* GFM 脚注: 锚点偏移补偿 sticky header */
[id^="user-content-fn"] {
  scroll-margin-top: 5rem;
}
 
/* 脚注区域样式 */
.footnotes {
  margin-top: 2rem;
  padding-top: 1rem;
  border-top: 1px solid var(--border);
  font-size: 0.875rem;
  color: var(--muted-foreground);
}

零宽字符测试：a\u200B b\u200C c\u200D

const UNICODE_ESCAPE_PATTERN = /\\u([0-9a-fA-F]{4})/g;
 
// 在 sanitizeNode 遍历中
if (child.type === "text" && UNICODE_ESCAPE_PATTERN.test(child.value)) {
  child.value = child.value.replace(UNICODE_ESCAPE_PATTERN, (_match, hex) =>
    String.fromCharCode(parseInt(hex, 16)),
  );
}

<MDXTabs defaultValue="tab1">
  <div value="tab1">Tab 1 内容</div>
  <div value="tab2">Tab 2 内容</div>
</MDXTabs>

interface TabInfo {
  value: string;
  label: string;
}
 
function extractTabInfo(children: ReactNode): TabInfo[] {
  const tabs: TabInfo[] = [];
  for (const child of Children.toArray(children)) {
    if (isValidElement(child)) {
      const props = child.props as Record<string, unknown>;
      if (typeof props.value === "string" && props.value) {
        tabs.push({
          value: props.value,
          label: typeof props.label === "string" ? props.label : props.value,
        });
      }
    }
  }
  return tabs;
}
 
// MDXTabs 内部
const needsAutoTabs = !hasTabsList(children);
const tabInfo = needsAutoTabs ? extractTabInfo(children) : [];

<!-- 形式 1: 最简写法，使用 value 作为标签文字 -->
 
<MDXTabs defaultValue="basic">
  <div value="basic">基础内容</div>
  <div value="advanced">高级内容</div>
</MDXTabs>
 
<!-- 形式 2: 带 label，显示更友好的标签文字 -->
 
<MDXTabs defaultValue="tab1">
  <section value="tab1" label="配置说明">
    详细的配置步骤...
  </section>
  <section value="tab2" label="代码示例">
    代码块内容（省略代码块标记以避免嵌套问题）
  </section>
</MDXTabs>

<MDXTabs.Tab value="x">内容</MDXTabs.Tab>
<Icon.displayName />
<Callout.InvalidChild>文本</Callout.InvalidChild>

_createMdxContent() {
  const MDXTabs = _provideComponents().MDXTabs;
  const _components = { /* ... */ };
  return (
    <>
      <MDXTabs.Tab value="x">内容</MDXTabs.Tab>
      <Icon.displayName />
    </>
  );
}

Error: Element type is invalid: expected a string (for built-in components)
or a class/function (for composite components) but got: undefined.

// mdx-components.tsx
function withSafetyGuard<T extends React.ComponentType>(componentName: string, Component: T): T {
  return new Proxy(Component, {
    get(target, prop) {
      // 0. React 内部属性白名单：直接透传
      const reactInternalProps = new Set([
        "$$typeof",
        "toJSON",
        "displayName",
        "propTypes",
        "defaultProps",
        "contextTypes",
        "childContextTypes",
      ]);
      if (reactInternalProps.has(String(prop))) {
        return Reflect.get(target, prop);
      }
 
      // 1. 正常访问：属性存在或为 Symbol
      if (prop in target || typeof prop === "symbol") {
        return Reflect.get(target, prop);
      }
 
      // 2. 异常访问：返回安全的 Fallback 组件
      const attemptedComponent = `${componentName}.${String(prop)}`;
 
      // 记录警告（生产环境仅第一次）
      if (!global.__mdxProxyWarnings) {
        global.__mdxProxyWarnings = new Set();
      }
      if (!global.__mdxProxyWarnings.has(attemptedComponent)) {
        global.__mdxProxyWarnings.add(attemptedComponent);
        console.error(
          `[MDX-Security-Shield]: 检测到非法组件引用 <${attemptedComponent} />。\n` +
            `  原因: MDX v3 不支持点记法语法 (Component.SubComponent)。\n` +
            `  影响: 系统已自动拦截并降级为普通文本，内容已保留，页面未崩溃。\n` +
            `  建议: 使用标准 MDX 语法或参考文档中的自动检测语法。`,
        );
      }
 
      // 3. 返回透明降级组件
      const SafeFallback = ({ children }: { children?: React.ReactNode }) => (
        <span
          className="mdx-fallback-text"
          data-attempted-component={attemptedComponent}
          data-reason="Unsupported dot notation syntax in MDX v3"
          title={`原始语法: <${attemptedComponent}> (不支持)`}
        >
          {children}
        </span>
      );
      SafeFallback.displayName = `SafeFallback(${attemptedComponent})`;
      return SafeFallback;
    },
  }) as T;
}
 
// 应用代理保护所有组件
export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // ... 其他组件 ...
    Callout: withSafetyGuard("Callout", Callout),
    Icon: withSafetyGuard("Icon", Icon),
    MDXTabs: withSafetyGuard("MDXTabs", MDXTabs),
    MDXTabsList: withSafetyGuard("MDXTabsList", MDXTabsList),
    MDXTabsTrigger: withSafetyGuard("MDXTabsTrigger", MDXTabsTrigger),
    MDXTabsContent: withSafetyGuard("MDXTabsContent", MDXTabsContent),
  };
}

/* app/globals.css */
.mdx-fallback-text {
  display: inline;
  color: var(--muted-foreground);
  transition: all 0.2s ease;
}
 
.mdx-fallback-text:hover {
  outline: 1px dashed var(--destructive);
  outline-offset: 2px;
  background-color: var(--destructive);
  opacity: 0.1;
}
 
/* 生产环境下移除调试样式 */
@media (prefers-reduced-data: reduce) {
  .mdx-fallback-text:hover {
    outline: none;
    background-color: transparent;
  }
}

<Icon.displayName />
<MDXTabs.InvalidChild>文本内容</MDXTabs.InvalidChild>

<!-- Icon.displayName 被拦截，降级为空 span -->
<span
  class="mdx-fallback-text"
  data-attempted-component="Icon.displayName"
  title="原始语法: <Icon.displayName> (不支持)"
></span>
 
<!-- MDXTabs.InvalidChild 被拦截，保留子内容 -->
<span
  class="mdx-fallback-text"
  data-attempted-component="MDXTabs.InvalidChild"
  title="原始语法: <MDXTabs.InvalidChild> (不支持)"
  >文本内容</span
>

[MDX-Security-Shield]: 检测到非法组件引用 <Icon.displayName />。
  原因: MDX v3 不支持点记法语法 (Component.SubComponent)。
  影响: 系统已自动拦截并降级为普通文本，内容已保留，页面未崩溃。
  建议: 使用标准 MDX 语法或参考文档中的自动检测语法。

<!-- ❌ 编译失败：MDX 无法解析嵌套点记法 -->
 
<MDXTabs.Invalid.NestedAccess value="x" />

Error: Expected component `MDXTabs.Invalid.NestedAccess` to be defined:
you likely forgot to import, pass, or provide it.