Django 项目中正确引入 CSS 静态文件的完整教程-html教程-PHP中文网

Django 项目中正确引入 CSS 静态文件的完整教程

在 Django 中，HTML 模板无法直接通过相对路径（如 href="stylepage.css"）引用 CSS 文件，必须使用 {% static %} 模板标签配合正确的静态文件配置才能生效。

在 django 中，html 模板无法直接通过相对路径（如 `href="stylepage.css"`）引用 css 文件，必须使用 `{% static %}` 模板标签配合正确的静态文件配置才能生效。

Django 将模板（templates） 与静态资源（static files） 严格分离：.html 文件位于 templates/ 目录下，由 Django 渲染后返回给浏览器；而 .css、.js、图片等前端资源属于静态文件，需统一存放在 static/ 目录中，并通过 Django 的静态文件机制提供服务。

✅ 正确配置步骤

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

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

myproject/
├── manage.py
├── myproject/          # 主配置包
├── templates/          # 存放 index.html 等模板
└── static/               # ← 新建此目录
    └── stylepage.css     # ← 放置你的 CSS 文件

? 建议按应用分目录（如 static/myapp/stylepage.css），便于后期维护，但基础用法中扁平结构即可。

2. 配置 settings.py

确认以下设置已启用（Django 默认已配置，但请检查）：

# myproject/settings.py
import os

# 静态文件根目录（开发时 Django 自动收集的路径）
STATIC_URL = '/static/'
STATICFILES_DIRS = [
    os.path.join(BASE_DIR, 'static'),
]
# 生产环境推荐使用 STATIC_ROOT + collectstatic，此处暂不展开

3. 在 urls.py 中启用开发期静态服务（仅 DEBUG=True）

在项目主 urls.py（如 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')),  # 示例应用路由
]

# ⚠️ 仅在开发环境启用！生产环境由 Nginx/Apache 托管
if settings.DEBUG:
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

4. 修改 HTML 模板：加载静态标签并正确引用

将原始标签替换为 Django 静态语法：

<!-- 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>

? 注意：{% static 'stylepage.css' %} 中的路径是相对于 STATICFILES_DIRS 中定义的目录（即 static/ 下的子路径），不是相对于 HTML 文件位置。

5. 验证与调试技巧

启动开发服务器：python manage.py runserver
打开浏览器开发者工具（F12）→ Network 标签页 → 刷新页面 → 查看 stylepage.css 是否返回 200 OK
若返回 404，请检查：
- static/stylepage.css 文件是否存在且拼写正确；
- settings.py 中 STATICFILES_DIRS 路径是否指向正确目录；
- 模板中是否遗漏 {% load static %}；
- URL 是否被意外覆盖（如 STATIC_URL = '' 或 None）。

? 重要注意事项

❌ 不要将 CSS 放在 templates/ 内——浏览器无法直接访问该目录；
❌ 不要使用或 href="./static/stylepage.css"——这是普通 HTML 写法，在 Django 中无效；
✅ 生产部署时，务必禁用 static() URL 配置，改用 Web 服务器（Nginx/Apache）托管静态文件，并运行 python manage.py collectstatic；

✅ 推荐为 CSS 添加版本参数防缓存（可选）：

<link rel="stylesheet" href="%7B%%20static%20'stylepage.css'%20%%7D?v=%7B%7B%20VERSION%20%7D%7D">

遵循以上流程，即可稳定、可扩展地在 Django 项目中管理所有前端静态资源。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索前端的入门与实战技巧！