如何初始化AWS Lambda中的submodule解决导入失败问题

本地运行正常是因为本地仓库执行过submodule初始化，对应目录下有完整代码；Lambda本身不感知git仓库结构，不管你是直接传zip、用控制台上传、还是走CI/CD部署，只要构建环节没显式处理submodule，部署包里的submodule路径就只是git生成的空占位文件夹，没有实际代码，自然导入失败。

方案1：构建环节提前拉取submodule代码（通用无改造，适配所有部署方式） #

这是成本最低的方案，不管你用什么渠道部署Lambda，只要在打包生成部署包之前，先执行submodule初始化命令，确保打包时submodule目录下有真实代码即可：

# 递归拉取所有层级submodule的完整代码
git submodule update --init --recursive
# 再执行原有打包流程，比如安装生产依赖、压缩部署包
npm ci --production
zip -r lambda-deploy.zip . -x "*.git*"

几个注意点：

• 压缩部署包时一定要排除.git相关目录，否则会把大量git元数据打进包里，徒增体积，甚至触发Lambda部署包大小限制
• 如果是在CodeBuild、GitHub Actions这类临时构建环境打包，克隆主仓库时要加--recurse-submodules参数，不要用默认浅克隆配置，否则后续执行submodule update可能拉取不到对应代码：

  git clone --recurse-submodules <你的主仓库地址>
  

• 如果是直接在控制台本地上传文件夹/zip，上传前先手动打开submodule对应的目录确认下，里面有实际代码文件再传，很多人本地因为submodule没初始化，目录是空的但资源管理器里显示有文件夹名，传上去自然报错。

方案2：用npm本地依赖替代git submodule（长期维护成本最低） #

如果你的submodule本身就是独立的NodeJS包，完全可以去掉git submodule的管理方式，直接把它作为本地npm依赖引入，从根源上避免submodule初始化的问题：
在package.json里声明本地路径依赖即可：

{
  "dependencies": {
    "your-submodule-name": "file:./path/to/your/submodule/dir"
  }
}

后续执行npm install/npm ci的时候，npm会自动把submodule的内容复制/软链到node_modules目录，本地和Lambda环境的导入逻辑完全一致，不需要额外记任何submodule相关的操作步骤，团队协作的时候也不会出现有人忘初始化submodule导致跑不起来的问题。

方案3：抽离为Lambda层（多函数复用场景适用） #

如果这个submodule是同账号下多个Lambda函数共用的公共代码，可以把submodule代码单独打包成Lambda层，层部署后会在函数运行时自动挂载到NodeJS的依赖加载路径下，所有绑定该层的函数都可以直接import对应的包，不需要每个函数部署的时候都重复打包submodule代码，能有效减小单个函数的部署包体积。
注意打包层的时候同样要提前执行submodule初始化，确保层的压缩包里有实际代码。

• 绝对不要在Lambda的handler执行逻辑里动态拉取submodule：Lambda运行时默认没有预装git，就算你手动打包git二进制进去，冷启动时拉代码会大幅增加冷启动耗时，还会碰到VPC网络访问、仓库权限配置等一堆额外问题，完全没有可行性
• 如果你用CDK、SAM这类IaC工具部署，不要依赖工具默认的构建逻辑，这类工具默认的构建步骤基本都不会自动拉取submodule，需要你在自定义构建脚本里手动加上submodule初始化的命令
• 打包完成后可以先本地解压部署包，检查下submodule对应的目录下是否存在实际的代码文件，确认没问题再上传，避免浪费部署和调试时间

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