为ReactJS项目添加自签名SSL证书遇启动脚本失效问题

核心原因分析 #

• 全局环境变量覆盖：如果系统中预先设置了SSL_CRT_FILE或SSL_KEY_FILE全局环境变量，会优先于package.json脚本里的局部配置，导致webpack-dev-server加载默认证书。
• react-scripts版本限制：旧版本的react-scripts可能不支持直接在启动脚本中传递SSL_CRT_FILE/SSL_KEY_FILE参数，变量无法被正确识别。
• 相对路径解析失败：webpack-dev-server启动时的工作目录可能并非项目根目录，./localhost.pem的相对路径无法定位到你的证书文件，自动 fallback 到默认的server.pem。
• 残留进程缓存：之前未完全关闭的dev-server进程仍在使用旧配置，新启动的进程继承了错误的证书设置。

分步修复方案 #

1. 排查并清除全局环境变量
   在终端执行对应命令检查全局变量：

   • Mac/Linux：echo $SSL_CRT_FILE
   • Windows：echo %SSL_CRT_FILE%
     如果输出非空内容，执行以下命令清除：
   • Mac/Linux：unset SSL_CRT_FILE && unset SSL_KEY_FILE
   • Windows：set SSL_CRT_FILE= && set SSL_KEY_FILE=

2. 升级react-scripts到最新稳定版
   旧版本对HTTPS配置的支持存在缺陷，执行升级命令：

   npm install react-scripts@latest
   

3. 验证并修正证书路径
   先确认证书文件存在于项目根目录：

   • Mac/Linux：ls ./localhost.pem
   • Windows：dir .\localhost.pem
     如果文件存在，尝试用绝对路径替换脚本中的相对路径，比如：

   "start": "HTTPS=true SSL_CRT_FILE=/Users/your-name/your-project/localhost.pem SSL_KEY_FILE=/Users/your-name/your-project/localhost-key.pem react-scripts start"
   

4. 彻底清除残留进程
   关闭所有终端窗口，通过任务管理器（Windows）或活动监视器（Mac）终止所有node.js相关进程，再重新执行npm start。

更可靠的替代配置方式 #

在项目根目录创建.env.development文件，写入以下内容：

HTTPS=true
SSL_CRT_FILE=./localhost.pem
SSL_KEY_FILE=./localhost-key.pem

react-scripts会自动读取该文件中的环境变量，避免脚本参数解析的潜在问题。

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