Next.js引入react-hook-mousetrap报模块外导入错误及动态导入受阻

刚安装完成react-hook-mousetrap，按照常规ES模块方式导入：

import useMousetrap from "react-hook-mousetrap";

直接触发编译报错：

SyntaxError: Cannot use import statement outside a module
> module.exports = require("react-hook-mousetrap");

一开始初步判断是Next.js SSR机制导致的问题：毕竟热键功能本质依赖浏览器端API，服务端渲染环境下无对应运行能力。

尝试过的无效方案 #

1. 最初考虑用next/dynamic做动态导入，但受限于“该方案仅适用于JSX/React组件懒加载”的认知，不知道如何直接导入使用React Hook。补充：该认知本身没有偏差，next/dynamic的核心能力就是组件级代码分割，本来就不是用来加载任意函数类模块的，用错场景自然无法落地。
2. 参考Next.js动态导入的相关逻辑，尝试用模块异步加载的方式处理，但碰到两个硬约束：
   • React Hook必须在组件顶层同步调用，不能嵌入异步流程
   • 不能将业务组件改造为异步组件，否则会破坏原有页面渲染逻辑
     实际尝试的两种写法全部失效：

   const MyComponent = () => {  
     // 失效写法1：组件内直接await导入
     // 问题：普通函数组件非异步函数，无法在顶层直接使用await语法
     const useMousetrap = await import("react-hook-mousetrap").default;
   
     // 失效写法2：组件内通过立即执行异步函数包裹导入逻辑
     // 问题：异步函数作用域内调用Hook违反React Hook使用规则
     (async () => {
       const useMousetrap = (await import("react-hook-mousetrap")).default;
       // 在此处调用Hook完全不合法
     })()
   }
   

首先明确根因：初始报错确实和模块格式、SSR双环境运行不兼容有关——react-hook-mousetrap本身是CommonJS格式打包的包，且依赖浏览器端专属API，服务端渲染阶段根本不需要加载执行它，完全不需要走复杂的异步导入流程，按以下两步处理即可：

1. 做环境适配的Hook引用：不需要异步等待，直接在组件外层做全局环境判断，给不同运行环境匹配对应的Hook实现：

   // 服务端环境下给一个空的占位Hook，不执行任何逻辑
   // 客户端环境下正常加载这个CommonJS模块
   const useMousetrap = typeof window !== "undefined"
     ? require("react-hook-mousetrap")
     : () => {};
   

2. 组件顶层正常调用Hook：适配后的Hook引用完全满足React Hook的调用规则，直接在组件顶层使用即可，不需要额外包裹异步逻辑：

   const MyComponent = () => {
     // 正常在顶层调用，服务端环境下实际执行的是空函数，不会触发浏览器API调用
     useMousetrap("ctrl+s", () => {
       saveCurrentPageData();
     })
   
     // 组件原有业务逻辑
   }
   

如果配置后仍碰到模块解析报错，可以在Next.js配置文件中把该库标记为服务端外部依赖，跳过服务端阶段的打包编译：

// next.config.js
module.exports = {
  serverExternalPackages: ["react-hook-mousetrap"]
}

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