如何在Next.js App Router中集成axe-core？

由于App Router采用服务端组件优先的架构，旧Pages Router中直接在ReactDOM渲染后调用axe初始化的方式不再适用。以下是可行的集成方案：

核心思路 #

通过客户端组件初始化axe-core，确保代码仅在浏览器环境运行，同时利用根Layout组件让所有页面都能接入无障碍检测。

步骤1：创建客户端初始化组件 #

新建app/AccessibilityChecker.tsx文件，添加'use client'指令标记为客户端组件，在组件内部通过useEffect动态导入并初始化axe-core：

'use client';

import { useEffect } from 'react';

export default function AccessibilityChecker() {
  useEffect(() => {
    const initAxe = async () => {
      // 仅在开发环境启用，避免生产环境加载冗余代码
      if (process.env.NODE_ENV !== 'production') {
        const axe = await import('@axe-core/react');
        const React = await import('react');
        const ReactDOM = await import('react-dom/client');

        // 初始化axe-core，第三个参数是检测间隔（毫秒），可按需调整
        axe.default(React, ReactDOM, 1000);
      }
    };

    initAxe();
  }, []);

  // 组件无需渲染任何内容
  return null;
}

步骤2：在根Layout中引入组件 #

修改app/layout.tsx，将上述组件添加到根布局中，确保所有页面都会加载axe初始化逻辑：

import AccessibilityChecker from './AccessibilityChecker';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="zh-CN">
      <body>
        <AccessibilityChecker />
        {children}
      </body>
    </html>
  );
}

自定义配置（可选） #

如果需要自定义axe的检测规则或配置，可以在初始化时传入配置对象：

axe.default(React, ReactDOM, 1000, {
  rules: {
    // 示例：禁用特定规则
    'color-contrast': { enabled: false },
  },
});

内容的提问来源于stack exchange，提问作者Loretta