Postwoman 项目中 JWT 令牌有效期配置问题解析

问题背景

Postwoman 项目（后更名为 Hoppscotch）是一个开源的 API 开发工具。在使用过程中，多位用户报告了关于 JWT（JSON Web Token）令牌有效期配置的问题，系统抛出错误提示："expiresIn" should be a number of seconds or string representing a timespan。

问题现象

用户在使用 Postwoman 的认证系统时，特别是在处理 Magic Link 登录和令牌生成过程中，后端服务会抛出上述错误。错误日志显示问题出现在 JWT 签名过程中，具体是在 jsonwebtoken 模块处理 expiresIn 参数时发生的验证失败。

根本原因分析

经过深入排查，发现问题的根源在于环境变量配置方式不当。具体表现为：

1. 时间单位混淆：部分用户将毫秒值直接作为 expiresIn 参数传递，而 jsonwebtoken 库期望的是秒数或时间跨度字符串（如 "1d"、"20h"）。

2. 环境变量格式错误：在 .env 文件中，用户错误地使用了内联注释，例如：

   REFRESH_TOKEN_VALIDITY=604800000 # 注释内容
   

   这种写法导致环境变量值实际上包含了注释部分，使得数值被错误解析。

解决方案

针对这一问题，我们推荐以下解决方案：

1. 正确的时间格式：

   • 使用秒数作为单位（而非毫秒）
   • 或使用可读性更强的时间跨度字符串，如 "7d" 表示7天

2. 规范的 .env 文件写法：

   • 避免在值后面添加内联注释
   • 注释应单独成行，以 # 开头

3. 推荐配置示例：

   # 令牌有效期配置
   REFRESH_TOKEN_VALIDITY=604800
   ACCESS_TOKEN_VALIDITY=86400
   

技术细节补充

JWT 有效期参数规范

jsonwebtoken 库对 expiresIn 参数有严格要求：

• 数字：表示秒数
• 字符串：支持的时间单位包括：
  • 秒（s）
  • 分钟（m）
  • 小时（h）
  • 天（d）

例如："1h30m" 表示1小时30分钟。

环境变量处理机制

大多数环境变量解析器（包括 Node.js 的 dotenv）不支持内联注释。当遇到类似配置时：

VAR=value # comment

实际读取的 VAR 值会是 "value # comment"，这显然不是我们期望的结果。

最佳实践建议

1. 配置验证：在应用启动时添加环境变量验证逻辑，确保关键配置符合预期格式。

2. 文档规范：在示例配置文件中，使用单独的注释行而非内联注释，避免误导用户。

3. 单位统一：建议团队内部统一使用秒或时间字符串作为时间单位，避免毫秒/秒混淆。

4. 错误处理：在令牌生成代码中添加更友好的错误提示，帮助用户快速定位配置问题。

总结

通过本文的分析，我们了解到在 Postwoman/Hoppscotch 项目中正确配置 JWT 令牌有效期的关键点。这不仅是简单的配置问题，更反映了开发中对第三方库参数规范和环境变量处理机制的深入理解需求。遵循这些最佳实践，可以避免类似问题的发生，确保认证系统的稳定运行。