如何在Next.js中动态导入非组件类JS库/模块？

问题本质 #

Next.js的dynamic API默认期望导入的是React组件（ComponentType），但你要导入的是依赖window的普通工具包，类型不匹配导致报错。

三种解决办法 #

1. 封装成React组件（适合在组件中渲染相关内容）

把工具包的使用逻辑封装到一个React组件里，再用dynamic导入这个组件：

// 页面或父组件中
import dynamic from 'next/dynamic';

const PackageWrapper = dynamic(() => import('../components/PackageWrapper'), {
  ssr: false,
});

// components/PackageWrapper.jsx
import React, { useEffect, useState } from 'react';
import npmPackage from 'npm-package';

export default function PackageWrapper() {
  const [data, setData] = useState(null);

  useEffect(() => {
    // 在这里调用npm包的方法
    const result = npmPackage.doSomething();
    setData(result);
  }, []);

  return <div>{data}</div>;
}

2. 在客户端生命周期中直接动态导入（无需组件包装）

如果只是需要调用包的方法、不需要渲染组件，直接在useEffect中动态导入（useEffect仅在客户端执行）：

import React, { useEffect } from 'react';

export default function MyPage() {
  useEffect(() => {
    const initTool = async () => {
      // 动态导入包
      const packageModule = await import('npm-package');
      // 根据导出方式调用：默认导出用packageModule.default，具名导出直接用packageModule.xxx
      packageModule.default.init();
    };
    initTool();
  }, []);

  return <div>页面内容</div>;
}

3. TypeScript类型兼容（跳过组件类型校验）

如果用TypeScript，不想调整代码结构，可以手动指定类型，绕过dynamic的组件类型限制：

import dynamic from 'next/dynamic';

// 强制转换类型为包本身的类型
const packageDynamic = dynamic(() => import('npm-package'), {
  ssr: false,
}) as unknown as typeof import('npm-package');

// 使用时注意：不能当作React组件渲染，只能作为工具库调用
// 比如在useEffect里：
useEffect(() => {
  packageDynamic.default.someMethod();
}, []);

额外优化建议 #

• 如果包支持按需导入，尽量只导入需要的模块，减少体积：import('npm-package/lib/needed-function')
• 确认包是否有服务端兼容版本，若有可以避免ssr:false的限制，但你这个包依赖window，大概率没有。

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