Rails 7集成esbuild后Capistrano部署失败的解决方法

问题背景 #

原Rails应用使用import map + Sprockets作为资源管道，后切换为cssbundling-rails（搭配Bootstrap）和jsbundling-rails（搭配esbuild）。部署到生产环境时，deploy:assets_precompile步骤崩溃，报错提示需要manifest.js，但esbuild并不依赖该文件。已尝试调整deploy.rb和Capfile但未解决，原本以为需要配置Capistrano以适配新的资源构建流程。

疑问点：

• 需要调整哪些Capistrano配置才能正常部署？
• 生产环境下CSS和JS文件该如何编译？
• 是否需要修改Nginx配置以加载资源？

解决方案 #

1. 安装Propshaft gem #

从Sprockets切换到css/js bundling工具后，Rails 7+推荐使用Propshaft作为新的资产管道（替代Sprockets）。未安装Propshaft时，应用会默认沿用Sprockets的逻辑，导致对manifest.js的依赖报错。

执行安装命令：

bundle add propshaft

2. 移除Sprockets版Bootstrap依赖 #

此前通过Sprockets安装的Bootstrap gem会强制依赖manifest.js，这是引发错误的核心原因。需要移除该旧gem，确保使用cssbundling-rails安装的Bootstrap（即通过npm管理的版本）。

检查并移除Gemfile中Sprockets相关的Bootstrap依赖，保留cssbundling-rails即可。

补充说明 #

生产环境CSS/JS编译 #

cssbundling和jsbundling会自动集成到Rails的assets:precompile任务中：

• 执行rails assets:precompile时，会自动触发package.json中配置的npm build脚本（比如esbuild的编译命令、Bootstrap的CSS构建命令）
• 编译后的资产文件会输出到public/assets目录，文件名包含哈希值用于缓存

Capistrano配置调整 #

• 确保Capfile中加载了capistrano/rails/assets：

  require "capistrano/rails/assets"
  

• 无需额外配置Sprockets相关内容，确保部署服务器已安装Node.js环境（因为需要运行npm命令）
• 如果之前有自定义Sprockets的Capistrano配置，建议移除

Nginx配置 #

一般无需修改Nginx配置：

• 新工具编译后的资产仍存放在public/assets目录，与Sprockets时代的路径兼容
• 确保Nginx配置中指向Rails应用的public目录，且location /assets配置正确（默认即可，无需额外调整）

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