使用npm工作区时，AWS SAM esbuild无法解析内部依赖@myProject/shared-types

背景 #

基于npm工作区的monorepo项目，包含shared-types工作区，用于向后端（AWS SAM + Typescript）和前端（Vite+React+Typescript）提供类型定义及可运行值。前端可正常使用shared-types中的值，但sam build触发esbuild构建时，导入这些值失败；类型定义可正常工作，推测运行时内容被esbuild丢弃。执行sam build前已构建shared-types。

报错信息 #

Error: NodejsNpmEsbuildBuilder:EsbuildBundle - Esbuild Failed: ✘ [ERROR] Could not resolve "@myProject/shared-types"

项目目录结构 #

.
└── packages
    ├── BACKEND
    ├── SHARED-TYPES
    └── FRONTEND

关键配置文件 #

根目录 package.json（节选） #

{
  "name": "@myProject/fullstack-monorepo",
  "workspaces": ["packages/*"],
  // ...
}

packages/SHARED-TYPES/package.json #

{
    "name": "@myProject/shared-types",
    "version": "1.0.0",
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
    "files": [
        "dist"
    ],
    "scripts": {
        "build": "tsc --build",
        "watch": "tsc --build --watch"
    },
    // ...
}

packages/SHARED-TYPES/tsconfig.json #

{
    "compilerOptions": {
        "target": "es2020",
        "module": "es2020",
        "strict": true,
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "composite": true,
        "declaration": true,
        "declarationMap": true,
        "rootDir": "src",
        "emitDeclarationOnly": false,
        "outDir": "dist",
        "moduleResolution": "Node",
        "incremental": true
    },
    "include": ["src/**/*"]
}

packages/BACKEND/package.json（节选） #

{
  "dependencies": {
    "@myProject/shared-types": "file:../SHARED-TYPES",
  }
}

AWS SAM template.yaml（节选） #

GetMetadataAllSurveys:
        Type: AWS::Serverless::Function
        Properties:
            # ...
        Metadata:
            BuildMethod: esbuild
            BuildProperties:
                EntryPoints:
                    - src/handlers/myHandler.ts
                External: ["@aws-sdk/*"]

排查方向与解决方法 #

1. 修正本地依赖引用方式 #

后端package.json中使用file:路径可能导致SAM的esbuild构建器无法正确解析工作区依赖，改用工作区协议：

{
  "dependencies": {
    "@myProject/shared-types": "1.0.0"
  }
}

npm工作区会自动识别同仓内的包版本，无需手动指定本地路径。

2. 明确共享包的导出规则 #

在shared-types的package.json中添加exports字段，确保esbuild能找到正确的运行时入口：

"exports": {
  ".": "./dist/index.js",
  "./types": "./dist/index.d.ts"
}

3. 调整模块格式兼容Lambda环境 #

AWS Lambda默认使用CommonJS模块，而shared-types当前编译为ES模块，可二选一调整：

• 方案一：修改shared-types的tsconfig：

  "compilerOptions": {
    "module": "CommonJS",
    "target": "ES2018"
  }
  

• 方案二：在SAM配置中指定esbuild输出ES模块：

  Metadata:
      BuildMethod: esbuild
      BuildProperties:
          Format: esm
          # 其他原有配置...
  

4. 确保SAM构建阶段安装依赖 #

在SAM的BuildProperties中添加安装命令，保证依赖被正确链接：

Metadata:
    BuildMethod: esbuild
    BuildProperties:
        # 原有配置...
        InstallCommands:
            - npm install

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