如何在 Django 项目中正确引入 CSS 静态文件-html教程-PHP中文网

本文详解 django 中静态资源（如 css）的正确加载方式，涵盖目录结构配置、url 路由设置、模板语法使用及开发/生产环境差异，解决“html 渲染正常但样式不生效”的常见问题。

本文详解 django 中静态资源（如 css）的正确加载方式，涵盖目录结构配置、url 路由设置、模板语法使用及开发/生产环境差异，解决“html 渲染正常但样式不生效”的常见问题。

在 Django 中，直接在 HTML 模板里用是无效的——因为浏览器无法访问 templates/ 目录（该目录仅用于服务端渲染），而 stylepage.css 若未按 Django 静态文件规范存放和引用，请求将返回 404，样式自然不会生效。

✅ 正确做法：遵循 Django 静态文件管理规范

1. 创建并组织静态文件目录

在项目根目录（与 manage.py 同级）新建 static/ 文件夹，并将 CSS 文件放入其中：

myproject/
├── manage.py
├── myproject/          # 主配置包
├── myapp/              # 应用目录
└── static/             # ← 必须存在且命名准确
    └── stylepage.css   # ← 放在此处（支持子目录，如 static/css/stylepage.css）

? 提示：Django 默认从 STATICFILES_DIRS 列表中查找静态文件。若你将 static/ 放在项目根目录，通常无需额外配置；但建议在 settings.py 中显式确认：
# settings.py
import os
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')  # 仅用于 collectstatic，开发时可不设
STATICFILES_DIRS = [
    BASE_DIR / "static",  # 确保指向你的 static/ 目录
]

2. 配置 URL 以支持开发期静态文件服务

在根 urls.py（即 myproject/urls.py）中，添加 static() 路由（仅限 DEBUG=True 的开发环境）：

# myproject/urls.py
from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static  # ← 导入关键模块

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('myapp.urls')),
] 

# ⚠️ 仅在 DEBUG=True 时启用（开发用）
if settings.DEBUG:
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

? 注意：STATIC_ROOT 是运行 python manage.py collectstatic 时合并所有静态文件的目标目录，开发阶段通常不需要设置 STATIC_ROOT，而是确保 document_root=settings.STATICFILES_DIRS[0] 或直接使用 STATICFILES_DIRS 对应路径。更稳妥的写法是：
if settings.DEBUG:
    urlpatterns += static(settings.STATIC_URL, document_root=BASE_DIR / "static")

3. 在模板中正确引用静态文件

修改 HTML 模板：必须先加载 {% load static %}，再用 {% static %} 模板标签生成绝对路径：

<!-- templates/index.html -->
{% load static %}  <!-- ← 关键：声明使用 static 标签 -->


    <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>TheWebPub</title><link rel="stylesheet" href="%7B%%20static%20'stylepage.css'%20%%7D"><!-- ← 正确引用 -->
    {% if name %}
        <h1 class="title">Hello {{ name }}.</h1>
    {% else %}
        <h1>Hello world.</h1>
    {% endif %}
    <p>Thank you for being here in my website, it's my first one. I'm creating this website with Django/Python.</p>

✅ 验证是否成功

启动开发服务器后，打开浏览器开发者工具（F12）→ Network 标签页 → 刷新页面，查找 stylepage.css 请求：

✅ 成功：状态码 200，响应内容为你的 CSS 代码；
❌ 失败：状态码 404，检查路径拼写、static/ 目录位置、{% load static %} 是否遗漏。

? 重要注意事项

不要把 CSS 放在 templates/ 下：模板目录仅用于 HTML 渲染，不提供 HTTP 访问；
{% static %} 是唯一可靠方式：它会自动拼接 STATIC_URL（如 /static/）前缀，适配不同部署环境；
生产环境必须由 Web 服务器托管静态文件：Nginx/Apache 需配置 location /static/ 指向 STATIC_ROOT；Django 不负责生产静态服务；
缓存问题：浏览器可能缓存旧 CSS，开发时可强制硬刷新（Ctrl+F5）或禁用缓存（DevTools → Network → ☑ Disable cache）。