Railsのエラー『TemplateError: Asset was not declared to be precompiled in production』の解決方法

このエラーは、Railsの本番環境でアセット（CSS、JS、画像など）が適切にプリコンパイルされていない場合に発生する。本番環境ではアセットが事前にコンパイルされる必要があり、未登録のアセットは読み込めないため、このエラーが起こることがある。

エラーの発生条件

• 本番環境でアセットを使用しようとしたが、プリコンパイルされていない
• config.assets.precompile に適切なアセットが含まれていない
• アセットパイプラインが適切に設定されていない

エラーメッセージの例

Sprockets::Rails::Helper::AssetNotPrecompiled in Pages#index
Asset `custom.js` was not declared to be precompiled in production.

アセットをプリコンパイルする

本番環境でアセットをコンパイルするには、以下のコマンドを実行する。

bin/rails assets:precompile

config.assets.precompile の確認

config/initializers/assets.rb に必要なアセットが含まれているか確認する。

Rails.application.config.assets.precompile += %w( custom.js custom.css )

アセットの配置場所の確認

アセットが適切な場所にあるか確認する。たとえば、app/assets/javascripts にあるべきファイルが vendor/assets/javascripts にあると、プリコンパイルされないことがある。

プリコンパイル済みアセットのクリア

古いアセットが原因でエラーが発生する場合がある。以下のコマンドでキャッシュをクリアする。

bin/rails assets:clobber
bin/rails assets:precompile

config/environments/production.rb の設定確認

以下の設定が適切に行われているか確認する。

config.assets.compile = false
config.public_file_server.enabled = true

public/assets にファイルが存在するか確認

本番環境でプリコンパイルされたアセットが public/assets ディレクトリ内に存在するか確認する。

Webpacker を使用している場合の対応

Webpacker を使用している場合、以下のコマンドでアセットをコンパイルする。

RAILS_ENV=production bin/webpack

本番環境のデプロイ時にプリコンパイルを実行

本番環境にデプロイする際、Capistrano などを使用している場合は、deploy.rb に以下を追加する。

namespace :deploy do
  after :updated, 'deploy:compile_assets'
end

まとめ

• プリコンパイルのコマンドを実行する
• config.assets.precompile を適切に設定する
• アセットの配置場所を確認する
• 古いアセットを削除して再コンパイルする
• 本番環境の設定を見直す