Yarn Workspaces通过AWS CodeBuild部署至ElasticBeanstalk的构建部署问题

项目结构 #

+-- node_modules
+-- package.json
+-- tsconfig.json
+-- buildspec.yml
+-- my-common
    |   +-- package.json
    |   +-- tsconfig.json
    |   +-- src
        |   +-- index.ts
+-- backend
    |   +-- package.json
    |   +-- tsconfig.json
    |   +-- src
        |   ...
+-- frontend
    |   +-- package.json
    |   +-- tsconfig.json
    |   +-- src
        |   ...

根目录 package.json 配置 #

{
  "main": "backend/dist/main.js",
  "name": "app-name",
  "private": true,
  "scripts": {
    "build": "yarn workspace my-common build && yarn workspace backend run build",
    "build:fe": "yarn workspace my-common build && yarn workspace frontend run build",
    "start": "node backend/dist/main.js",
    "start:dev": "yarn workspace backend start:dev & yarn workspace frontend start:dev"
  },
  "version": "0.0.1",
  "workspaces": [
    "frontend",
    "backend",
    "my-common"
  ]
}

问题现象 #

前端通过AWS Amplify构建部署正常，但后端用CodePipeline+CodeBuild交付时，构建阶段全过，但实例启动报错：

Error: Cannot find module 'my-common'

下载CodeBuild制品压缩包后发现node_modules里没有my-common包。本地Mac环境执行相同步骤，node_modules里有指向my-common工作区的符号链接，归档解压后也能保留。

1. 符号链接丢失的原因 #

• CodeBuild默认归档工具（如zip）未启用保留符号链接的参数，会直接忽略符号链接或仅归档链接本身，而非目标文件；本地Mac的zip工具默认支持符号链接归档，因此能保留。
• CodeBuild构建环境是隔离的，部分归档工具打包时不会解析工作区符号链接，导致制品缺失my-common的实际代码文件。

2. 能否强制npm/yarn复制文件夹而非创建符号链接？ #

Yarn 1.x Workspaces默认用符号链接关联工作区包，没有直接配置强制复制的选项。仅能通过手动复制等临时方式实现，但这类方法不推荐长期使用。

3. 无临时技巧的正确构建部署方案 #

推荐采用构建后将依赖打包进产物的方式，彻底避免符号链接依赖问题：

方案一：使用yarn pack打包工作区包 #

1. 在my-common目录执行yarn pack，生成.tgz格式的包文件。
2. 在构建脚本中动态安装该包到backend：

   # 构建阶段添加命令
   cd my-common && yarn pack --filename my-common.tgz
   cd ../backend && yarn add ../my-common/my-common.tgz
   

   此方式会将my-common的完整代码复制到backend的node_modules中，而非符号链接。

方案二：TypeScript路径映射+编译打包 #

1. 在backend的tsconfig.json中配置路径映射，直接指向my-common源码或构建产物：

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "my-common": ["../my-common/src"]
       }
     }
   }
   

2. 使用tsconfig-paths或webpack（若后端用webpack打包），将my-common代码直接打包进backend的dist目录，部署时无需依赖node_modules中的符号链接。

方案三：调整CodeBuild归档命令 #

修改buildspec.yml，使用支持保留符号链接的归档参数：

post_build:
  commands:
    # zip的-y参数用于保留符号链接
    zip -yr backend-artifact.zip backend/dist node_modules my-common

注意：此方式要求部署环境能正确解析符号链接，且my-common的目录结构在部署时与构建时完全一致，否则会出现路径错误。

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