Django项目中HTML无法加载独立CSS文件的问题排查与解决

问题表现 #

• CSS代码直接内嵌在main.html的<style>标签中时，页面样式显示正常；将CSS抽离为独立文件后，所有样式均不生效
• 项目内所有业务HTML页面均继承自main.html公共模板

相关代码片段 #

main.html的head标签原始代码 #

<head>
    <title>ToDoList App</title>

    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="description" content="">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous"> -->
    <link id="sheet-theme" rel="stylesheet" type="text/css" href="light.css"> 

    <!-- Nunito Font -->
    <link rel="preconnect" href="https://fonts.gstatic.com">
    <link href="https://fonts.googleapis.com/css2?family=Nunito:wght@200&display=swap" rel="stylesheet">
</head>

继承公共模板的注册页示例代码 #

{% extends 'base/main.html' %}

{% block content %}

    <div class="header-bar">
        <h1>Register</h1>
    </div>

    <div class="card-body">
        <form method="POST">
            {% csrf_token %}
            {{form.as_p}}
            
            <input style="margin-top: 16px" class="button" type="submit" value="Register">
        </form>

        <p>已有账号？请<a id="plain" href="{% url 'login' %}">登录</a></p>
    </div>

{% endblock content %}

核心原因 #

问题根源是不符合Django的静态资源管理规则：

• 直接使用相对路径href="light.css"引用CSS文件，Django无法将该路径映射到实际的静态资源文件
• 静态资源没有放在Django可识别的静态文件目录下，无法被正常加载

修复步骤 #

1. 在base应用目录下创建层级目录static/base，将抽离的CSS文件全部放入该目录
2. 修改main.html的代码，先加载静态资源标签，再调整CSS引用语句：

<!-- 页面最开头先加载static标签 -->
{% load static %}
<head>
    <title>ToDoList App</title>
    <!-- 其余meta标签、字体引用保持不变 -->
    <!-- 修改CSS引用为static模板语法 -->
    <link id="sheet-theme" rel="stylesheet" type="text/css" href="{% static 'base/light.css' %}"> 
</head>

3. 确认项目根目录的settings.py中存在以下静态资源配置（默认生成的Django项目自带该配置，无需额外修改）：

STATIC_URL = 'static/'

修改完成后重启Django服务即可正常加载独立CSS文件，后续新增的JS、图片等静态资源也可以按照相同规则存放和引用。

内容的提问来源于stack exchange，提问作者Filip Szczybura