Rails-React应用部署因文件名大小写不一致致esbuild打包失败

问题根源 #

开发环境（如macOS）多采用大小写不敏感的文件系统，而生产服务器（Linux）是严格大小写敏感的。同时esbuild的路径匹配严格区分大小写，再加上Capistrano部署时的缓存或Git同步疏漏，导致统一PascalCase命名后出现文件找不到的报错。

解决方案 #

1. 严格统一文件名与导入语句的大小写 #

• 所有React组件文件采用PascalCase命名（例如Resources.jsx），对应的导入语句必须完全匹配文件名的大小写：

  // 正确
  import Resources from './Resources';
  // 错误（本地能运行但生产环境会报错）
  import Resources from './resources';
  

• 遍历所有组件文件和导入语句，包括嵌套目录下的组件，确保100%匹配。

2. 清理本地与服务器的缓存 #

• 本地清理：删除生成的构建文件和esbuild缓存，重新测试打包：

  rm -rf app/assets/builds/*
  rm -rf node_modules/.cache
  npm run build
  

• 服务器端清理：在Capistrano的deploy.rb中添加缓存清理任务，确保部署前清空旧的构建文件：

  namespace :deploy do
    desc 'Clean esbuild assets and node cache'
    task :clean_assets_cache do
      on roles(:web) do
        execute "rm -rf #{release_path}/app/assets/builds/*"
        execute "rm -rf #{release_path}/node_modules/.cache"
      end
    end
  end
  
  # 在预编译前执行清理
  before 'deploy:assets:precompile', 'deploy:clean_assets_cache'
  

3. 优化esbuild构建脚本 #

当前的通配符app/javascript/*.*可能匹配到残留的大小写不一致文件，改为指定明确的入口文件：

{
  "scripts": {
    "build": "esbuild app/javascript/application.js --bundle --sourcemap --outdir=app/assets/builds --public-path=assets"
  }
}

如果有多个入口文件，直接列出（如app/javascript/application.js app/javascript/admin.js），避免通配符带来的意外匹配。

4. 确保Git同步大小写变更 #

Git默认区分文件名大小写，但直接修改文件名可能不会被Git识别。使用git mv命令重命名文件并提交：

# 重命名文件并让Git识别变更
git mv app/javascript/components/resources.jsx app/javascript/components/Resources.jsx
git commit -m "Rename component to PascalCase to match React conventions"
git push

之后重新部署，确保服务器拉取到正确的文件名。

5. 验证服务器文件状态 #

登录生产服务器，进入部署目录，检查组件文件的实际命名：

ls -la /path/to/deployed/app/app/javascript/components/

确认文件名与本地完全一致（PascalCase），如果仍有不一致，重新执行git mv提交后再次部署。

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