できない.dev

Django で静的ファイル(CSS・JS)が 404 になり読み込めない

Django で静的ファイルが 404 になるときは、本番なら collectstatic で集めて Web サーバから配信すれば直る。
runserver が配信するのは DEBUG = True のときだけだ。

公開: 更新:

症状できない
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/static/admin/css/base.css
404
解決後できた
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/static/admin/css/base.css
200

2026-10-23 に python:3.12(Django 6.1.2) で実際に打って取った出力。検証環境の詳細

要約

django.contrib.staticfiles を入れたプロジェクトでは、runserver が /static/ 配下のファイルを自動で配信する。
ただしこれは DEBUG = True のときだけの動作で、公式ドキュメントは「非常に非効率で、おそらく安全でもない」ため本番には向かないと明記している。

そのため、DEBUG = False に切り替えた途端に、CSS や JavaScript などの静的ファイルだけが 404 になる。
本番では次の 2 段階で配信する。

python manage.py collectstatic
# 集まった STATIC_ROOT を Web サーバから配信する

実行例

python:3.12 のコンテナに Django 6.1.2 を入れ、admin 同梱の /static/admin/css/base.css を取りに行って試した。
既定の DEBUG = True の runserver は 200 を返した。
DEBUG = False にすると 404 になり、--insecure を付けると 200 に戻った。
STATIC_ROOT が未設定の collectstatic は、ImproperlyConfigured で終了コード 1 になった。
STATIC_ROOT を決めると、130 ファイルがコピーされて終了コード 0 になった。
STATICFILES_DIRS に STATIC_ROOT と同じディレクトリを入れると、python manage.py check が staticfiles.E002 で終了コード 1 になった。
別のディレクトリにすると通った。
トレースバックは最終行だけを載せている。

$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/static/admin/css/base.css
200
$ tail -n 3 mysite/settings.py
DEBUG = False
ALLOWED_HOSTS = ["127.0.0.1"]
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/static/admin/css/base.css
404
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/static/admin/css/base.css
200
$ python manage.py collectstatic --noinput
django.core.exceptions.ImproperlyConfigured: You're using the staticfiles app without having set the STATIC_ROOT setting to a filesystem path.
$ echo $?
1
$ tail -n 1 mysite/settings.py
STATIC_ROOT = BASE_DIR / "staticfiles"
$ python manage.py collectstatic --noinput
130 static files copied to '/tmp/tmp.ghaPLmUi44/staticfiles'.
$ echo $?
0
$ ls staticfiles
admin
$ tail -n 1 mysite/settings.py
STATICFILES_DIRS = [BASE_DIR / "staticfiles"]
$ python manage.py check
SystemCheckError: System check identified some issues:
 
ERRORS:
?: (staticfiles.E002) The STATICFILES_DIRS setting should not contain the STATIC_ROOT setting.
 
System check identified 1 issue (0 silenced).
$ echo $?
1
$ tail -n 2 mysite/settings.py
STATICFILES_DIRS = [BASE_DIR / "staticfiles"]
STATICFILES_DIRS = [BASE_DIR / "static"]
$ python manage.py check
System check identified no issues (0 silenced).
$ echo $?
0

— 2026-10-23 時点の出力

検証環境Python 3.12.15 / Git 2.47.3 / Django 6.1.2 / 2026-10-23 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.15
  • Git 2.47.3
  • Django 6.1.2

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. ローカルでは DEBUG を戻すか --insecure を使う

DEBUG = False の挙動を手元で確かめたいときは、--insecure を付けると静的ファイルも配信される。

python manage.py runserver --insecure

公式ドキュメントは、このオプションはローカル開発専用で本番では決して使わないよう警告している。
DEBUG = False にするなら、ALLOWED_HOSTS の設定も同時に必要になる。

2. collectstatic して Web サーバから配信する

STATIC_ROOT が未設定のまま collectstatic を実行すると、次のエラーになる。

django.core.exceptions.ImproperlyConfigured: You're using the staticfiles app without having set the STATIC_ROOT setting to a filesystem path.

STATIC_ROOT を決めて、デプロイのたびに collectstatic を実行する。

# settings.py
STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
python manage.py collectstatic --noinput

成功すると … static files copied to '<STATIC_ROOT のパス>'. の形で、コピーした件数が表示される。
集めたディレクトリを、nginx などで STATIC_URL のパスに割り当てる。

location /static/ {
    alias /app/staticfiles/;
}

3. STATIC_ROOT は置き場所と分ける

STATIC_ROOT は collectstatic の出力先で、ファイルを手で置く場所ではない。
STATICFILES_DIRS と同じディレクトリを指定すると、システムチェックで止まる。

?: (staticfiles.E002) The STATICFILES_DIRS setting should not contain the STATIC_ROOT setting.

4. アプリに属さないファイルは STATICFILES_DIRS に登録する

STATICFILES_DIRS = [BASE_DIR / "static"]

アプリのファイルは blog/static/blog/app.css のように、アプリ名のサブディレクトリを挟んで置く。
公式ドキュメントは、別のアプリに同じ名前のファイルがあると Django が区別できず、最初に見つかったものを使うため名前空間を切るよう説明している。
テンプレートでは {% load static %} の後に {% static "blog/app.css" %} で URL を組み立てる。

よくある原因

  1. DEBUG = False にした。
    このとき runserver の静的ファイル配信は止まる。
    ページ本体は表示されるのに、スタイルが外れた状態になる。
  2. collectstatic を実行していない。
    本番の Web サーバは各アプリの static/ を見に行かない。
    collectstatic で 1 か所に集め、そのディレクトリを配信する必要がある。
  3. STATIC_ROOT が設定されていない。
    既定値は None で、このまま collectstatic を実行すると ImproperlyConfigured で止まる(全文は解決策 2)。
  4. STATICFILES_DIRS が無い。
    Django が標準で探すのは各アプリの static/ サブディレクトリだ。
    プロジェクト直下の static/site.css は、DEBUG = True でも登録しない限り 404 になる。