React可用的@tensorflow-models/speech-commands在NextJS中报错问题排查

为什么NextJS会报fs模块找不到的错误？ #

• NextJS默认采用服务器端渲染（SSR）或静态站点生成（SSG）模式，构建阶段会在Node.js环境下预解析所有模块导入。@tensorflow-models/speech-commands虽为浏览器设计，但其源码中可能包含针对Node环境的条件性fs模块引用（比如某些仅在Node环境触发的文件读取逻辑）。NextJS在服务器端打包时会尝试解析这个fs导入，而该模块仅存在于Node环境，最终导致模块找不到的错误。
• 你之前尝试的普通动态导入或window存在性判断，无法阻止NextJS在服务器端预解析模块依赖——即便代码逻辑里有window判断，打包工具在服务器端仍会扫描到fs的导入语句并尝试解析。

为什么React环境下能正常运行？ #

纯React应用（比如Create React App搭建的项目）是纯客户端渲染模式，其打包工具（Webpack）默认配置了忽略Node.js核心模块（如fs）的导入。打包时会自动将这些仅适用于Node环境的模块引用置为空或直接忽略，不会触发解析错误，因此speech-commands能正常在浏览器中运行。

解决方法 #

要确保speech-commands仅在客户端环境加载，需使用NextJS的动态导入并禁用SSR：

// 在app/audio/page.tsx中导入组件时
import dynamic from 'next/dynamic';

const AudioComponent = dynamic(() => import('../components/audio'), {
  ssr: false, // 强制组件仅在客户端渲染
  loading: () => <p>加载中...</p>
});

export default function AudioPage() {
  return <AudioComponent />;
}

这样配置后，NextJS会跳过该组件的服务器端预解析，仅在浏览器环境中加载组件及其依赖，fs模块的导入不会被触发，自然也就不会报错。

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