使用 osls 快速管理 AWS Lambda Layers：共享依赖与第三方库的完整指南

osls 是一个开源的 Serverless Framework CLI，用于部署和管理 AWS Lambda 等无服务器应用。本文介绍如何使用 osls 配置和部署 AWS Lambda Layers，实现多函数共享依赖与第三方库的完整方案，帮助你控制部署包体积、统一依赖版本并支持跨账号共享。

为什么需要 Lambda Layers

Lambda 函数的部署包有大小限制，当多个函数依赖相同的第三方库（如数据库驱动、SDK 客户端）时，把公共依赖打进每个函数的 zip 包会造成体积浪费和版本漂移。Lambda Layers 将公共依赖打包为独立的"层"，挂载到函数上，一次构建、处处复用。

osls 对 Layers 的支持开箱即用：只需在 serverless.yml 中声明，osls deploy会自动完成打包、上传、发布新版本并挂载。完整官方说明见 docs/guides/layers.md。

在 serverless.yml 中声明 osls Layers

所有层都在服务配置的layers顶层属性中声明，osls 会自动将其编译为 CloudFormation 的AWS::Lambda::LayerVersion资源（核心逻辑位于 lib/plugins/aws/package/compile/layers.js）。

基础配置：指向本地目录

# serverless.yml service: myService provider: name: aws layers: hello: path: layer-dir # 必填，本地层内容的目录 name: ${sls:stage}-layerName # 可选，AWS 中的层名 description: 共享的第三方依赖层 # 可选

可选参数速查表

配置样例可参考测试夹具 test/fixtures/programmatic/function-layers/serverless.yml。参数合法性由 osls 的配置 schema 校验，定义见 lib/plugins/aws/provider.js。

使用预构建 artifact

如果 CI 流程已经产出层包（例如 Maven、Bun 生成的 zip），可以跳过path直接指定：

layers: layerOne: package: artifact: dist/my-layer.zip

也可以只通过patterns精细控制层的打包内容，且 pattern 是相对层的path解析的：

layers: layerOne: path: layerOne package: patterns: - '!layerSourceTarball.tar.gz'

将层挂载到函数

同服务内的层：用 CloudFormation Ref

同一serverless.yml内定义的层，用!Ref引用。逻辑 ID 规则是"层名转 TitleCase +LambdaLayer"（见 lib/plugins/aws/lib/naming.js），例如层test的逻辑 ID 就是TestLambdaLayer：

layers: test: path: layer functions: hello: handler: handler.hello layers: - !Ref TestLambdaLayer

外部层：直接用 ARN

挂载其它服务或第三方提供的层，直接写 ARN；函数层最多挂载 5 个：

functions: hello: handler: handler.hello layers: - arn:aws:lambda:us-east-1:111111111111:layer:MyPublicLayer:7

服务级默认层：provider.layers

想让全部函数都加载某些层（如全局监控 agent），可以配置在服务级，省得逐个函数声明：

provider: name: aws runtime: nodejs24.x layers: - arn:aws:lambda:us-east-1:111111111111:layer:layer1:3

跨账号共享与权限控制

通过allowedAccounts可以让其它 AWS 账号访问你发布的层版本（osls 会为每个账号生成AWS::Lambda::LayerVersionPermission资源）：

layers: layerOne: path: layerOne allowedAccounts: - 111111111111 # 指定账号 - arn:aws:iam::222222222222:root

写- '*'则对全部账号公开，请务必谨慎（参见 docs/guides/layers.md 中的 Permissions 一节）。

部署与验证：自动跳过重复上传

部署时 osls 会计算层包内容哈希，并与上次部署的 Stack Output 对比（见 lib/plugins/aws/package/compile/layers.js）：

• 内容没变化 → 直接复用已有的 S3 Key，终端提示Layer xxx is already uploaded.，不重复上传，加快部署；
• 内容有变化 → 自动发布新层版本，并将函数指向新版本。

每次部署后，层的QualifiedArn、内容Hash与S3Key都会写入 Stack Outputs（命名规则见 lib/plugins/aws/lib/naming.js），用osls info --verbose即可查看层当前版本。命令详情参考 docs/cli-reference/info.md。

日常开发只改函数代码时，可用更快的 osls deploy function 单独发布函数，无需走完整的 CloudFormation 更新。

本地调试：invoke local 自动拉取层

osls 的本地调用会真实模拟层环境（实现见 lib/plugins/aws/invoke-local/index.js）：

• 引用同服务定义的层：直接使用本地path目录；
• 指定了package.artifact的层：自动解压到.serverless/layers/下使用；
• 外部 ARN 层：自动从 AWS 下载并缓存，第二次运行不再重复下载。

因此本地执行osls invoke local -f hello时，require就能解析到层内的依赖，与线上行为一致。

打包策略与 CI/CD 最佳实践

• 层默认继承服务级package.patterns，也可在层级单独指定，两者按各自path解析；
• 配合package.individually: true可让不同函数使用独立部署包，进一步优化体积（详见 docs/guides/packaging.md）；
• CI/CD 场景推荐osls package先构建产物，再osls deploy --package <dir>部署，保证构建与部署环境一致；注意打包与部署的 stage/region 必须匹配。

相关文档与源码索引 📚

• 官方指南：docs/guides/layers.md
• 层编译逻辑：lib/plugins/aws/package/compile/layers.js
• 逻辑 ID 与 Outputs 命名：lib/plugins/aws/lib/naming.js
• 层 schema 校验规则：lib/plugins/aws/provider.js
• 端到端配置示例：test/fixtures/programmatic/function-layers/serverless.yml

掌握以上内容，你就可以用 osls 把共享依赖、第三方库的构建、部署与共享权限纳入同一条serverless.yml工作流，获得可预测、可回滚且跨账号可复用的 Lambda Layers 方案 ✅