Serverless Offline读取AWS SSM参数而非本地.env文件问题

问题原因 #

Serverless框架默认会优先加载通过SSM配置的环境参数，即便本地存在.env文件，后续加载的SSM参数也会覆盖已读取的.env变量。单独安装dotenv无效，是因为Serverless Offline的环境变量加载逻辑在dotenv之后，会重新覆盖process.env。

解决方案 #

方法1：通过Stage区分环境加载变量

通过Serverless的stage变量，让本地运行时仅读取.env，部署时读取SSM参数。

1. 新建/修改env.yml文件，按环境拆分配置：

local:
  DB_HOST: ${env:DB_HOST}
  DB_PORT: ${env:DB_PORT}
  DB_USER: ${env:DB_USER}
  DB_PASSWORD: ${env:DB_PASSWORD}
  DB_NAME: ${env:DB_NAME}
prod:
  DB_HOST: ${ssm:/prod/db/host}
  DB_PORT: ${ssm:/prod/db/port}
  DB_USER: ${ssm:/prod/db/user}
  DB_PASSWORD: ${ssm:/prod/db/password}
  DB_NAME: ${ssm:/prod/db/name}

2. 修改serverless.yml，根据当前stage加载对应配置：

provider:
  name: aws
  runtime: nodejs18.x
  environment:
    ${file(./env.yml):${self:provider.stage}}

custom:
  serverless-offline:
    stage: local

plugins:
  - serverless-offline

3. 本地启动命令：

serverless offline start --stage local

此时本地运行会读取.env变量，部署时切换到prod stage即可加载SSM参数。

方法2：用serverless-dotenv-plugin确保.env优先级

安装专门的Serverless dotenv插件，让.env变量优先加载，覆盖后续的SSM参数。

1. 安装插件：

npm install serverless-dotenv-plugin --save-dev

2. 修改serverless.yml，将插件放在serverless-offline之前：

plugins:
  - serverless-dotenv-plugin
  - serverless-offline

custom:
  serverless-dotenv-plugin:
    # 配置是否覆盖已存在的环境变量
    override: true

启动后插件会优先加载.env，覆盖SSM参数。

方法3：本地运行时禁用SSM加载

在serverless.yml中通过条件判断，仅在非本地stage加载SSM参数：

provider:
  name: aws
  runtime: nodejs18.x
  environment:
    ${self:custom.localEnv, ''}
    ${self:custom.prodEnv, ''}

custom:
  localEnv:
    ${if:eq(self:provider.stage, 'local'), {
      DB_HOST: ${env:DB_HOST},
      DB_PORT: ${env:DB_PORT},
      DB_USER: ${env:DB_USER},
      DB_PASSWORD: ${env:DB_PASSWORD},
      DB_NAME: ${env:DB_NAME}
    }, ''}
  prodEnv:
    ${if:ne(self:provider.stage, 'local'), {
      DB_HOST: ${ssm:/prod/db/host},
      DB_PORT: ${ssm:/prod/db/port},
      DB_USER: ${ssm:/prod/db/user},
      DB_PASSWORD: ${ssm:/prod/db/password},
      DB_NAME: ${ssm:/prod/db/name}
    }, ''}
  serverless-offline:
    stage: local

plugins:
  - serverless-offline

同样用serverless offline start --stage local启动本地服务，此时不会加载SSM参数。

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