Serverless Framework V4本地.env环境变量读取失败求助

问题现象 #

使用Serverless V4搭建项目，搭配serverless-offline插件、Node.js v21.7.1版本，调用接口时process.env中的自定义变量返回undefined，触发500错误，日志输出如下：

{ port: 3000, hostawayApiKey: undefined, hostawayId: NaN }

解决方案 #

1. 确认.env文件的正确性 #

• 确保.env文件放置在项目根目录，文件名严格为.env（不可使用.env.dev、.env.local等变体，除非额外配置加载规则）
• 变量格式需规范，避免多余空格或引号：

  HOSTAWAY_API_KEY=your_real_api_key
  HOSTAWAY_ID=123456
  PORT=3000
  

2. 在serverless.yml中显式绑定环境变量 #

Serverless V4默认支持加载.env，但显式配置变量可确保其正确传递到函数执行环境：

provider:
  name: aws
  runtime: nodejs20.x
  # 添加环境变量绑定
  environment:
    HOSTAWAY_API_KEY: ${env:HOSTAWAY_API_KEY}
    HOSTAWAY_ID: ${env:HOSTAWAY_ID}
    PORT: ${env:PORT, '3000'} # 可选：设置默认值

3. 升级serverless-offline至兼容版本 #

部分旧版serverless-offline与Serverless V4存在兼容性问题，执行命令升级：

npm update serverless-offline --save-dev

4. 手动加载.env文件（兜底方案） #

若上述方法无效，使用dotenv包手动加载环境变量：

• 安装依赖：

  npm install dotenv --save
  

• 在配置文件最顶部添加加载代码：

  // 放在文件最开头，确保优先加载环境变量
  require('dotenv').config();
  
  const config = {
    port: process.env.PORT || 3000,
    hostawayApiKey: process.env.HOSTAWAY_API_KEY,
    hostawayId: parseInt(process.env.HOSTAWAY_ID)
  }
  
  module.exports = config;
  

5. 检查启动命令 #

确保使用serverless offline命令启动服务，而非直接运行Node脚本，这样Serverless框架才能完整加载环境变量配置。

验证方式 #

重启serverless-offline服务，调用/login接口，查看日志是否输出正确的配置值：

{ port: 3000, hostawayApiKey: 'your_real_api_key', hostawayId: 123456 }

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