Ariakit React 在 CJS 构建中的 "use client" 指令问题解析

问题背景

在 Next.js 应用中使用 Ariakit React 库时，当项目通过 CommonJS (CJS) 模块系统构建时，会出现一个特殊的编译错误。错误提示表明 "use client" 指令的位置不正确，必须放在文件的最前面。这个问题主要影响那些由于依赖链关系而被迫使用 CJS 构建的项目。

问题本质

Ariakit React 的 CJS 构建输出文件中，"use client" 指令被放在了 "use strict" 和模块定义代码之后。根据 Next.js 的规范，"use client" 这样的指令必须出现在文件的最开始位置。当前的构建输出格式如下：

"use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";

而正确的格式应该是：

"use client"; "use strict";Object.defineProperty(exports, "__esModule", {value: true});

技术原因

这个问题源于构建工具链的处理顺序：

1. Rollup/tsup 在生成 CJS 输出时，会自动添加 "use strict" 指令和 ES 模块转换代码
2. 然后才会应用通过 banner 选项添加的 "use client" 指令
3. 这种顺序导致了指令位置不符合 Next.js 的要求

影响范围

主要影响以下场景：

• 使用 styled-components v5 等不支持 ESM 的库的项目
• 需要发布 CJS 格式的组件库
• 这些组件库又依赖 Ariakit React 的项目
• 在 Next.js 应用目录(app dir)中使用这些组件库时

解决方案

Ariakit 团队已经通过以下方式修复了这个问题：

1. 移除了 CJS 构建中的 "use client" banner
2. 将指令直接添加到源代码文件中
3. 确保指令出现在文件最前面

对于开发者来说，临时解决方案包括：

• 使用 pnpm patch 手动修改 node_modules 中的文件
• 等待官方发布修复版本

技术启示

这个问题揭示了几个重要的技术点：

1. 现代 React 生态中 ESM 和 CJS 的兼容性问题仍然存在
2. 构建工具链对指令的处理顺序会影响最终输出
3. 指令在文件中的位置有时会直接影响功能
4. 组件库的发布格式会影响下游应用

最佳实践建议

对于库开发者：

• 优先支持 ESM 格式
• 谨慎处理指令的添加位置
• 考虑不同构建环境下的输出差异

对于应用开发者：

• 尽量使用 ESM 格式的依赖
• 了解项目依赖链中的模块格式
• 关注上游库的更新情况

这个问题展示了现代前端开发中模块系统和构建工具复杂性的一个典型案例，理解这些底层机制有助于更好地诊断和解决类似问题。