Heroku部署Rails应用assets预编译失败 凭证主密钥解密报错

你遇到的ArgumentError: key must be 16 bytes报错，本质是配置到Heroku的RAILS_MASTER_KEY值不符合Rails对主密钥的格式要求——Rails的加密主密钥固定需要是16字节的随机串，对应32位连续的十六进制字符，只要复制的密钥带了空格、漏了字符、错粘了其他内容，长度凑不够16字节，就会在assets预编译读取加密凭证的时候直接抛错，哪怕本地开发环境运行完全正常也会卡住部署流程。
之前重新生成主密钥没解决问题，核心原因是Heroku上存的环境变量值没有和当前正确的主密钥做逐字匹配，旧的错误值没有被彻底清除覆盖。

1. 拿到合法的本地主密钥精确值 #

• 打开你本地项目根目录下的config/master.key文件，直接复制文件内的全部字符串：
  • 该字符串必须是连续的32位十六进制字符（仅包含0-9、a-f），没有前后空格、换行符
  • 不要错把config/credentials.yml.enc的密文内容、或者其他配置文件的内容当成主密钥
• 先在本地生产环境模式验证凭证读取是否正常：执行RAILS_ENV=production rails runner "puts Rails.application.credentials.myapikey[:key].inspect"，能正常输出凭证内容就说明拿到的主密钥是配对正确的。

2. 清空Heroku上的旧错误配置 #

• 把之前设置过的错误主密钥变量彻底删掉，避免残留覆盖：执行heroku config:remove RAILS_MASTER_KEY
• 重新把刚才核对好的主密钥值配置上去，注意粘贴时不要带入多余的空格、换行：执行heroku config:set RAILS_MASTER_KEY=[你从config/master.key里复制的精确字符串]
• 立刻校验Heroku上存的密钥值是否正确：执行heroku config:get RAILS_MASTER_KEY，对比输出的字符串长度是否为32位、和本地的config/master.key内容逐字匹配。特别要留意输出的内容前后有没有不可见的空格、换行——很多人设置环境变量时没注意，让密钥值前后多了不可见字符，直接导致长度不匹配触发报错。

3. 排查容易遗漏的关联配置 #

• 无需刻意修改config/environments/production.rb里的config.require_master_key注释状态：Rails生产环境默认会优先读取环境变量里的RAILS_MASTER_KEY，只要值正确，这行配置是否开启不影响正常运行。
• 检查.gitignore文件规则：如果config/master.key被加入git忽略列表，确保推送到Heroku的代码包里没有这个文件，完全依赖环境变量读取主密钥时，更要保证环境变量值的精确匹配。
• 确认config/credentials.yml.enc加密文件和当前主密钥配对：如果之前重新生成过主密钥，要检查加密文件没有残留旧版本内容，避免主密钥长度正确但内容不匹配，再次触发ActiveSupport::MessageEncryptor::InvalidMessage报错。

4. 本地预校验后再部署 #

• 推送代码到Heroku之前，先在本地执行RAILS_ENV=production bundle exec rake assets:precompile，本地能无报错完成预编译后，再执行git push heroku部署，避免反复触发部署失败。

注意：不要尝试手动修改密钥长度凑够16字节，必须使用和credentials加密文件配对的原生随机密钥，手动调整的密钥哪怕长度合规，也没法解密凭证内容。

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