Django 静态文件 404 错误排查与正确配置指南-html教程-PHP中文网

Django 静态文件 404 错误排查与正确配置指南

本文详解 Django 项目中 JavaScript 文件（如 current_time.js）因静态资源配置不当导致的 404 1804 错误，涵盖 settings.py、URL 路由及模板引用的完整配置方案，确保 CSS 和 JS 均能正常加载。

本文详解 django 项目中 javascript 文件（如 `current_time.js`）因静态资源配置不当导致的 `404 1804` 错误，涵盖 `settings.py`、url 路由及模板引用的完整配置方案，确保 css 和 js 均能正常加载。

在 Django 开发中，模板成功加载 CSS 却无法加载 JS（报错 "GET /static/current_time.js HTTP/1.1" 404 1804），通常并非路径书写错误，而是静态文件服务机制未正确启用或配置冲突所致。核心原因在于：Django 默认仅在开发阶段通过 django.contrib.staticfiles 提供静态资源服务，但需满足三要素——正确的设置项、URL 路由映射、以及符合目录约定的文件位置。

✅ 正确配置步骤

1. 确保 settings.py 中静态文件配置完整

# settings.py
import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent.parent

# 静态文件基础配置（必填）
STATIC_URL = "static/"  # 浏览器请求静态资源时的 URL 前缀（如 /static/current_time.js）

# 开发阶段：指定源文件所在目录（即你存放 current_time.js 的位置）
STATICFILES_DIRS = [
    BASE_DIR / "static",      # ? 注意：这是你的源静态文件根目录（如 myproject/static/）
]

# 构建阶段：collectstatic 命令输出目标目录（开发时可暂不深究，但必须定义）
STATIC_ROOT = BASE_DIR / "staticfiles"

⚠️ 关键点：STATICFILES_DIRS 必须指向实际存放 current_time.js 的父目录。根据你的结构 myapp/static/current_time.js，若该 static 文件夹位于 myapp/ 下而非项目根目录，则应改为：

STATICFILES_DIRS = [
    BASE_DIR / "myapp" / "static",  # 或使用 os.path.join(BASE_DIR, 'myapp', 'static')
]

2. 在主 urls.py 中显式启用静态文件服务（仅限开发环境）

# myproject/urls.py
from django.contrib import admin
from django.urls import path, re_path
from django.views.static import serve
from django.conf.urls.static import static
from django.conf import settings

urlpatterns = [
    path('admin/', admin.site.urls),
    # 其他应用路由...
]

# ? 开发阶段：手动添加静态文件路由（DEBUG=True 时生效）
if settings.DEBUG:
    urlpatterns += [
        re_path(r'^static/(?P<path>.*)$', serve, {
            'document_root': settings.STATIC_ROOT
        }),
    ]
    # 同时支持 STATIC_URL 映射（更推荐的写法）
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)</path>

? 提示：static(...) 辅助函数会自动为 STATIC_URL 添加路由规则；re_path 手动注册是冗余但兼容性更强的方式。二者选一即可，推荐使用 static()。

Django Unfold
提供使用 django-unfold (v0.56+) 构建高级 Django 管理界面的专业指导。当用户提及 django-unfold、unfold admin 等内容时使用此技能。

下载

3. 模板中正确引用静态资源

Django 模板中必须使用 {% static %} 模板标签（已加载 {% load static %}），不可硬编码 /static/...：

{% load static %}
<!-- ✅ 正确：由 Django 动态解析路径 -->
<script src="%7B%%20static%20'current_time.js'%20%%7D"></script><!-- ❌ 错误：绕过 Django 静态文件系统，易出错 --><!-- <script src="/static/current_time.js"></script> -->

同时确认 current_time.js 文件确实位于 STATICFILES_DIRS 指定的任一目录下（例如 myproject/static/current_time.js 或 myproject/myapp/static/current_time.js）。

? 排查与验证技巧

运行 python manage.py findstatic current_time.js —— 查看 Django 是否能定位到该文件；
访问 http://127.0.0.1:8000/static/current_time.js 直接测试 URL 可达性；
检查浏览器开发者工具 Network 标签页，确认请求的完整 URL 是否与 STATIC_URL 一致；
确保 DEBUG = True（生产环境需用 Nginx/Apache 服务静态文件，static() 不生效）。

✅ 总结

404 错误本质是“Django 不知道去哪里找你的 JS 文件”。解决关键在于：
① STATICFILES_DIRS 准确指向源文件目录；
② urls.py 主动挂载静态文件路由（开发期）；
③ 模板始终使用 {% static %} 标签而非硬编码路径。
完成上述配置后，current_time.js 将与 style_time.css 一样被正常加载，实时显示系统时间。