NextJS中如何在CLI运行时忽略'server-only'并确保库不被客户端导入

要同时实现「禁止客户端导入该库」和「本地脚本可正常使用」，可以从以下几个方向处理：

方案一：环境变量控制server-only导入 #

修改lib/server-only-library.ts，通过环境变量判断是否为本地脚本环境，仅在非本地环境下导入server-only：

// lib/server-only-library.ts
// 仅在非本地脚本环境加载server-only
if (!process.env.LOCAL_SCRIPT) {
  import('server-only');
}

// 你的库代码
export default function ServerLibrary() {
  // ...
}

运行本地脚本时，通过环境变量标记本地环境：

LOCAL_SCRIPT=true tsx scripts/local-script.ts

原理：Next.js客户端环境不会设置LOCAL_SCRIPT变量，因此会正常导入server-only，一旦客户端尝试导入该库就会抛出错误；本地脚本运行时通过环境变量跳过server-only的导入，避免报错。

方案二：为本地脚本配置模块别名 #

创建一个空的server-only替代模块，让本地脚本运行时用它替换真实的server-only：

1. 在scripts目录下创建mock-server-only.ts：

// scripts/mock-server-only.ts
// 空模块，仅用于本地脚本替代server-only

2. 创建专门的脚本配置文件tsconfig.scripts.json：

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "paths": {
      "server-only": ["./scripts/mock-server-only.ts"]
    }
  }
}

3. 运行本地脚本时指定该配置文件：

tsx --project tsconfig.scripts.json scripts/local-script.ts

原理：本地脚本通过自定义tsconfig将server-only映射为空模块，不会触发报错；Next.js构建使用默认tsconfig，仍会加载真实的server-only模块，保证客户端导入限制生效。

为什么之前的Webpack配置无效？ #

你之前的Webpack配置仅作用于Next.js的构建流程，而本地脚本是通过tsx直接在Node环境运行，不走Webpack的模块解析逻辑，因此该别名对本地脚本完全不起作用。

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