Serverless Framework 变量Variables与 Resolver 体系全解析从${}动态配置到多账号解析原理【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless变量系统是 Serverless Framework 配置能力的基石它允许你在serverless.yml中用${}语法动态引用环境变量、CLI 参数、外部文件、Git 信息、AWS SSM/S3 等外部数据源并结合 stage 实现多环境差异化配置。本文以 docs/sf/guides/variables/README.md 为主线完整讲解变量语法、Resolver/Provider 机制、默认值回退与递归引用并深入packages/sf-core的解析器源码帮助你既能直接上手配置也能理解框架底层如何解析与替换的实现原理。变量语法入门${}引用与默认值在 Serverless Framework 中变量Variable允许你在serverless.yml的属性值中动态替换配置内容。它最常见的两个用途是为服务提供密钥secrets以及在多 stage 工作流中提供差异化配置。使用方式是将引用值用${}包裹# serverless.yml file yamlKeyXYZ: ${provider:resolver:key} # see list of current resolver providers below # this is an example of providing a default value as the second parameter otherYamlKey: ${provider:resolver:key, defaultValue}其中${provider:resolver:key}是完整的解析式provider是解析提供方名称resolver是解析器名称key是待解析的数据键例如 SSM 参数路径、S3 的bucket/key。重要限制变量只能出现在serverless.yml属性的值中不能用于属性键。例如不能在 custom resources 段落中通过变量生成动态 Logical ID——因为键的位置不会被变量系统扫描处理。从源码看占位符收集器collectFromObject只递归遍历对象的value而不会改写key见 placeholders.js。Resolver 与 Provider变量的两级抽象**Variable Resolvers变量解析器**允许你在serverless.yml中引用外部数据源。每个 Resolver 都有一个Provider父级Provider 负责获取凭证credentials。例如awsProvider 下挂载了ssm与s3两个 Resolver分别从 AWS SSM Parameter Store 和 S3 拉取数据。Provider 还可以暴露内置变量例如awsProvider 的accountId。这类变量由 Provider 直接解析无需额外配置凭证来源使用部署凭证本身。自定义 Provider 与 Resolver你可以在stages段的resolvers块中自定义 Provider/Resolver 配置随后用${customProviderName:customResolverName:key}语法引用自定义版本。stages: default: resolvers: awsAccount1: type: aws profile: dev-account1-profile-name awsAccount2: type: aws profile: dev-account2-profile-name euS3: # custom resolver configuration defined for the awsAccount2 provider type: s3 region: eu-west-1 prod: resolvers: awsAccount1: type: aws profile: prod-account1-profile-name awsAccount2: type: aws profile: prod-account2-profile-name euS3: # custom resolver configuration defined for the awsAccount2 provider type: s3 region: eu-west-1 functions: hello: handler: handler.hello environment: ACCOUNT1_ID: ${awsAccount1:accountId} # built-in variable provided by the AWS provider SSM_VALUE: ${awsAccount1:ssm:/path/to/param} # uses the default resolver configuration even if its not explicitly defined in the resolvers block EU_S3_VALUE: ${awsAccount2:euS3:myBucket/myKey} # uses the customized resolver configuration S3_VALUE: ${awsAccount2:s3:myBucket/myKey} # uses the default resolver configuration even if a customized one (euS3) is defined for the same provider这个例子的语义要点default与prod两个 stage 各自定义了相同的 Provider 名但 profile 不同——框架解析时只保留当前 stage 与default的配置源码中由pruneUnusedStages()删除无关 stage见 manager.js从而天然实现同配置、多环境切换凭证。${awsAccount1:accountId}引用的是aws类型 Provider 的内置变量。${awsAccount2:euS3:myBucket/myKey}用的是自定义解析器euS3region 固定为eu-west-1。${awsAccount2:s3:myBucket/myKey}即便同名 Provider 下定义了自定义euS3仍会解析为默认的s3Resolver 配置。关键规则即使你不显式定义也始终可以引用 Provider 提供的默认 Resolver。例如直接用${aws:s3:myBucket/myKey}它会使用部署所用的同一 AWS Provider即凭证提供方与默认 Resolver 配置若定义了自定义 Provider 配置则可用${customProviderName:s3:myBucket/myKey}。与底层实现对照上述两级抽象在源码中有清晰对应每个 Provider 是一个继承自AbstractProvider的类类上通过静态字段声明type、resolvers、defaultResolver见 providers/index.js实际 Provider 类由providerRegistry注册维护registry/index.js。createResolverProviderproviders.js按配置创建 Provider 实例并把 provider 配置对象中所有{ type: ... }形式的分支注册为自定义 ResolveraddResolversForProvider随后再补齐该 Provider 的其余默认 ResolverProvider.resolvers这就从实现上保证了默认 Resolver 永远可用。凭证解析由AbstractProvider.resolveCredentials()钩子负责且同一时刻只保存一份凭证 promise避免并发重复获取自定义 Provider 的profile等配置正是凭证获取的输入。当配置中存在多个type: aws的 Provider 而provider.resolver未指定时框架会直接报错要求显式指定部署凭证来源未定义任何自定义 Provider 时则回退到default-aws-credential-resolver用部署默认凭证链逻辑见 manager.js。支持的变量 Provider 清单框架内置了多类 Provider每个都可以像上面的语法一样按${provider:key}或${provider:resolver:key}引用。完整清单与独立文档如下路径均为仓库根相对路径Self-References引用serverless.yml自身属性Serverless 核心变量Core Variables环境变量Environment VariablesCLI 选项CLI Options外部 YAML/JSON 文件External FilesJavaScript 动态取值Git 信息AWS含 SSM、S3、CloudFormation Outputs 等HashiCorp含 Terraform、Vault递归引用在变量中嵌套变量变量系统支持递归引用属性你可以把多个取值来源自由组合。一个经典场景是把 stage 嵌入到文件名中按环境加载不同配置文件provider: name: aws environment: MY_SECRET: ${file(./config.${sls:stage}.json):CREDS}如果执行sls deploy --stage qastage 被置为qa内层${sls:stage}先解析为qa并拼入外层文件路径最终读取config.qa.json中的CREDS键赋给MY_SECRET。若执行sls deploy --stage prod则对应找到config.prod.json。解析的完整过程如下stage由命令行选项--stage qa决定如果命令行未提供则${sls:stage}回退到provider.stage的值仍未设置时默认取dev。内层${sls:stage}解析为qa并作为外层${file(...)}变量 key 的一部分参与求值。定位并读取./config.qa.json取出其中的CREDS值。将解析结果写入MY_SECRET属性。在底层这种先内后外的顺序并非靠简单的字符串替换完成。框架将每一个${}视为图Graph中的一个节点并通过依赖边保证嵌套占位符先于外层占位符被解析extractPlaceholdersFromString递归扫描字符串中所有${、}配对把内层占位符的解析结果回填到外层 key 中见 placeholders.js 与#updatePredecessorNodes对前驱节点的更新逻辑。若变量间形成循环引用框架会抛出RESOLVER_CYCLIC_REFERENCE错误并指明循环链路placeholders.js且整张图在 graph.js 中被并行处理以提升大配置的解析速度。用 Parameters 设置 stage 级变量有时你希望直接在serverless.yml中定义一个贯穿全文的变量。这时可以使用Parameters既能声明新变量也能设置按 stage 区分的变量值。下面的例子按 stage 设置域名stages: default: params: domain: ${sls:stage}.example-dev.com prod: params: domain: example.com provider: environment: APP_DOMAIN: ${param:domain}在dev环境默认 stage解析得到dev.example-dev.com在prod环境解析得到example.com。Params 的取值优先级与来源合并逻辑可在 manager.js 中看到最终 params 由 CLI--param选项、params.default、params.stage以及stages.stage.params等逐级合并得到。完整用法请参考 Parameters 文档。多配置文件拆分庞大的serverless.yml当serverless.yml中堆积了大量自定义资源时文件会迅速膨胀。借助变量语法可以把资源定义拆到独立文件中resources: Resources: ${file(cloudformation-resources.json)}cloudformation-resources.json中定义的资源会被解析并加载进Resources段。如果希望内联资源 外部文件资源并存可以把resources写成数组将多个来源合并resources: - Resources: ApiGatewayRestApi: Type: AWS::ApiGateway::RestApi - ${file(resources/first-cf-resources.yml)} - ${file(resources/second-cf-resources.yml)} - Outputs: CognitoUserPoolId: Value: Ref: CognitoUserPool注意每个 CloudFormation 文件都必须以Resources实体开头Resources: Type: AWS::S3::Bucket Properties: BucketName: some-bucket-name注此处示例沿用了原文档的写法实际部署时通常还需为该 Bucket 资源提供合理的Type与所属Resources:层级。默认值Default Values与回退策略框架提供了直观的多变量回退机制当第一个变量取不到值时自动尝试下一个来源从而为主数据源缺失的场景提供兜底默认值。例如用opt变量获取 CLI 选项运行serverless deploy --memory 2048时读取memory若未提供该选项则使用默认值1024。functions: hello: handler: handler.hello memorySize: ${opt:memory, 1024}默认值本身也可以是另一个变量形成链式回退例如${opt:memory, self:custom.defaultMemorySize}。底层实现中一个${a, b, c}会被拆解为多个 fallbackextractPlaceholderDetailsFromPlaceholderString用逗号切分出每个回退分支带引号的字面量被解析为literalValue否则继续按占位符解析placeholders.js。解析时按顺序逐个尝试各 fallback遇到null/空值则跳到下一个若全部失败则抛出RESOLVER_MISSING_VARIABLE_RESULT错误并提示请检查变量定义或提供默认值见 manager.js。将字符串变量读取为布尔值strToBool有些配置项要求布尔类型如true/false。当用变量提供该值时来源往往返回字符串——比如 SSM 参数读出来的就是true/false直接赋值会因类型不符而出错。此时可以用strToBool解析器把字符串显式转换为布尔值provider: tracing: apiGateway: ${strToBool(${ssm:API_GW_DEBUG_ENABLED})}转换规则先统一转为小写再判断${strToBool(true)} true ${strToBool(false)} false ${strToBool(True)} true ${strToBool(False)} false ${strToBool(TRUE)} true ${strToBool(FALSE)} false ${strToBool(0)} false ${strToBool(1)} true ${strToBool(2)} Error ${strToBool(null)} Error ${strToBool(anything)} Error也就是说只有true/1与false/0大小写不敏感是合法输入其余值一律抛错。其实现位于StrToBoolProviderstr-to-bool.js内部用trueStrings {true,1}、falseStrings {false,0}两个集合先对输入trim().toLowerCase()再做集合判定匹配失败即抛出含明确提示的错误。测试用例位于 packages/sf-core/tests/integration/resolvers/str-to-bool以 yml fixture 驱动端到端验证。核心变量slsinstanceId 与 stage框架内部本身也会初始化若干核心变量这些值通过{sls:}前缀暴露给用户复用。instanceIdinstanceId是每次运行 Serverless CLI 时生成的随机 ID适用于需要可预测的随机值的场景例如给 API Gateway 部署追加唯一后缀service: new-service provider: aws functions: func1: name: function-1 handler: handler.func1 environment: APIG_DEPLOYMENT_ID: ApiGatewayDeployment${sls:instanceId}在源码中它并不是真正的随机数而是new Date().getTime().toString()生成的时间戳字符串且在SlsProvider 的静态字段上缓存保证一次 CLI 运行周期内该值恒定见 sls.js。stagestage是当前 CLI 使用的 stage 值。${sls:stage}相当于快捷写法${opt:stage, self:provider.stage, dev}——即优先取--stage命令行选项其次取provider.stage最后默认dev。这与解析管理器resolveStage()的逻辑一致命令行未提供 stage 时从provider.stage取值provider.stage为空或可解析为占位符时最终落回devmanager.js。AWS 专属变量与配置速览awsProvider 除了提供ssm、s3、cfCloudFormation Outputs三类 Resolver 外还暴露几个常用内置变量详见 AWS Variables 文档${aws:accountId}基于已配置 AWS 凭证解析出的账号 ID。${aws:region}相当于${opt:region, self:provider.region, us-east-1}。${aws:partition}由 region 本地推导不发起 AWS API 调用用于拼接跨分区 ARN例如us-east-1 → aws、cn-north-1 → aws-cn、us-gov-west-1 → aws-us-gov未知区域回退awsservice: new-service provider: name: aws functions: func1: name: function-1 handler: handler.func1 environment: QUEUE_ARN: arn:${aws:partition}:sqs:${aws:region}:${aws:accountId}:my-queue自定义awsProvider 的常见配置项包括profile、region、accessKeyId/secretAccessKey/sessionToken、dashboard是否使用 Serverless Dashboard Provider 凭证等。各 Resolver 的独立文档可继续阅读 S3、SSM Secrets Manager、CloudFormation Outputs。解析引擎是怎么工作的一个图驱动的替换过程了解了上述所有变量用法后理解整个解析器的运转顺序会更有帮助。从 resolvers/index.js 与 manager.js 可以看到框架分阶段解析serverless.yml而不是一次性暴力替换校验配置ensureNoParamsAndStagesTogether、validateCustomResolverConfigs、validateResolversUniqueness分别校验 params 与 stages 是否混用、自定义 Resolver 配置是否合法、是否有重复名称validation.js。确定 stage无--stage时取provider.stage否则默认dev同时加载.env与.env.stage文件loadEnvFiles。首轮受限解析先用一组轻量 Providerenv、opt、file、sls、strToBool、git、self、param见 manager.js解析org、app、service、provider.region、params、provider.profile、provider.resolver等关键路径——因为这些路径可能决定后续凭证与阶段选择。确定凭证 Resolver依据provider.resolver、配置中type: aws的 Provider 数量决定谁提供部署凭证只保留当前 stage 与default段。二次扫描 全量解析重新收集占位符构建依赖图把自定义 Provider 与内置 Provider 一并注册进图然后按依赖边并行解析所有剩余占位符并回填到配置。输出明细若开启了相关输出printResult会以表格形式打印每个替换项含配置路径Path、原始值Original、解析结果Resolved以及 Provider/Resolver 类型明细便于排障见 index.js。顺带一提占位符语法本身也在 placeholders.js 中做了归一主正则^([^:()])(?:\((.*)\))?(?::(.*))?$负责解析${provider:resolver:key}与${file(...)}风格另一条 legacy 正则还兼容${ssm(...):...}、${s3(...):...}、${cf(...):...}等旧式写法并对${AWS::xxx}伪参数、CloudWatch 动态标签、Fn::Sub中的!字面量做豁免不当作变量解析。这也是为什么文档中的${ssm:API_GW_DEBUG_ENABLED}这类旧式写法依然能工作。小结本指南覆盖了 Serverless Framework 变量系统的完整脉络${}语法与只能用于属性值的约束、Provider/Resolver 两级抽象与默认 Resolver 始终可用的规则、自定义多账号 Provider、递归引用与回退默认值、strToBool类型转换、sls核心变量以及多配置文件拆分技巧。配合packages/sf-core的图驱动解析实现分阶段受限解析 → 依赖图 → 并行替换你可以更有把握地设计跨 stage、跨账号的安全动态配置并在解析失败时依据错误信息与源码快速定位问题。每个 Provider 的细化用法还可继续查阅前文支持的变量 Provider 清单中各子文档。【免费下载链接】serverless⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.项目地址: https://gitcode.com/GitHub_Trending/se/serverless创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考