Turborepo共享库引入Twilio报net模块找不到错误如何解决

API 探路者

2026-9-3

Turborepo+Next.js monorepo引入共享包Twilio报Module not found: Can't resolve 'net'修复方案

错误根因

Can't resolve 'net'是典型的Node原生模块被误打包到浏览器侧的报错：net是Node服务端内置的网络模块，浏览器环境不存在对应实现。Twilio SDK为纯服务端设计的依赖，内部通过https-proxy-agent引用net/tls等Node原生模块，该错误的核心原因是构建流程错误将Twilio相关代码打入了前端浏览器bundle，和共享包导出设计、Next.js构建配置、代码引入范围不规范直接相关。

可落地修复步骤

1. 从入口层面隔离服务端专属依赖，杜绝前端误引入

所有Twilio相关的引入代码，只能出现在Next.js的API路由、Server Components、getServerSideProps、Route Handler等纯服务端执行的文件中，绝对不能在带'use client'标记的客户端组件、页面组件、前端自定义hooks里引入Twilio实例。
拆分共享包导出入口，不要把服务端专属依赖和前端通用工具混在同一个入口导出：
- 在packages/library下新增server.ts作为服务端专用导出文件，仅导出Twilio、Plaid、Prismic这类依赖Node环境的实例
- 原index.ts只导出前后端通用的无Node依赖的工具函数
- 修改packages/library/package.json的导出映射，明确区分两个入口：
```
{
  "name": "@vero/library",
  "exports": {
    ".": "./src/index.ts",
    "./server": "./src/server.ts"
  },
  "dependencies": {
    "twilio": "^3.77.2"
  }
}
```
- 业务API路由中引入Twilio时，改为从@vero/library/server导入，从入口层面避免前端构建工具扫描到Twilio依赖。

2. 调整Next.js构建配置，兜底识别服务端模块

如果项目配置了transpilePackages: ['@vero/library']让Next.js编译共享包TS源码，需要在对应Next.js应用的next.config.js中补充webpack配置，客户端构建阶段直接忽略Node原生模块和纯服务端依赖：

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['@vero/library'],
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        net: false,
        tls: false,
        fs: false,
        dns: false,
        child_process: false,
        twilio: false,
        'https-proxy-agent': false
      }
    }
    return config
  }
}

module.exports = nextConfig

注意：该配置仅为兜底防护，不能替代第一步的入口隔离，否则会出现客户端调用到空模块的运行时错误。

3. 修正共享包依赖与构建配置

不要把twilio这类服务端专属依赖安装到monorepo根目录的devDependencies中，确保twilio仅作为@vero/library的dependency声明，业务应用不要重复安装twilio，避免依赖提升导致的模块解析错误。
如果共享库使用tsup/rollup等工具做预构建，需要给构建配置添加platform: 'node'参数，同时将twilio、net、tls等模块加入external列表，不要把这类Node专属代码打进共享库产物。

验证方式

修改完成后先清理所有构建缓存：删除各应用的.next目录、根目录及各包下的node_modules/.cache目录，重新执行turbo run dev启动项目：

浏览器加载的JS资源中不再包含twilio相关代码
调用/api/notify接口时，服务端可正常初始化Twilio客户端完成短信发送，无模块解析报错

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