Rails6升级应用在Dokku部署遇Webpack binstubs缺失致预编译报错

典型报错信息 #

webpack binstubs not found.
Have you run rails webpacker:install ?
Make sure the bin directory or binstubs are not included in .gitignore
Exiting!

!     Precompiling assets failed.

报错核心逻辑 #

Rails 6 版本开始原生将Webpacker作为默认前端资产处理选项，只要项目依赖中引入了Webpacker，不管是Heroku还是Dokku这类兼容其构建逻辑的平台，在执行资产预编译时都会自动校验Webpack相关binstub的存在性，不会因为是老项目平滑升级就跳过检查。之前参考的全新项目解决方案不适配的核心原因是：全新项目本身就会默认启用全量Webpacker配置，而老项目升级场景下，很多人只是升级了Rails版本，既没有主动安装Webpacker，也没处理Rails 6默认带来的依赖匹配逻辑，才会触发报错。

分场景排查解决步骤 #

场景1：完全不需要使用Webpack，仅想沿用原Rails 5.2时代的Sprockets资产管线 #

这是老项目升级最常见的误触发场景：

• 首先检查Gemfile，确认升级Rails版本时是不是误带入了gem 'webpacker'依赖。Rails 6的默认Gemfile模板会内置webpacker依赖，很多老项目升级时只修改了rails的版本号，没有清理模板引入的冗余依赖，就会强制触发Webpack检查逻辑。
• 直接删除或注释Gemfile里的webpacker依赖行，执行bundle install更新Gemfile.lock，重新提交代码后，构建流程会自动跳过Webpack相关检查，完全兼容原有Sprockets资产编译逻辑。

场景2：后续计划给老项目接入Webpacker，当前尚未完成配置 #

不要直接套用新建项目的全量安装命令rails webpacker:install——这个命令会强行覆盖老项目已有的视图、布局、脚本文件，极易引发业务逻辑异常：

• 先执行bundle add webpacker把依赖加入项目
• 按需选择最小侵入式的安装路径：
  • 无前端框架的纯基础JS场景，执行rails webpacker:install:base，只会生成必要的配置文件、对应binstub，不会修改项目原有业务代码
  • 后续需要接入React/Vue等前端框架时，再单独执行对应框架的子安装命令即可
• 检查.gitignore配置，确认没有把bin目录整体加入忽略列表。老项目升级时很多人会为了避免本地生成的binstub冲突，把整个bin目录加进gitignore，导致生成的binstub没有被提交到代码仓库，平台构建时自然找不到文件。
• 把生成的所有配置文件、binstub提交到代码仓库后，重新触发部署即可解决报错。

场景3：暂时无法完成Webpacker全量配置，需要快速完成部署 #

Dokku支持通过环境变量调整Webpacker的构建逻辑，适合刚升级还在灰度迁移的过渡场景：

• 在Dokku应用后台设置环境变量WEBPACKER_COMPILE=false，强制让资产预编译流程跳过Webpack的检查和执行逻辑，不需要立刻配完所有Webpack相关配置就能完成正常部署，后续等配置调试完成再取消这个环境变量即可。

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