اگر Static File ها در پروژه Django لود نمی شوند، معمولا مشکل از تنظیمات STATIC_URL، مسیر فایل ها، تنظیمات collectstatic یا پیکربندی وب سرور است. این مشکل یکی از رایج ترین دردسرهای برنامه نویسان جنگو محسوب می شود و مخصوصا هنگام Deploy پروژه روی سرور بیشتر دیده می شود. خوشبختانه در بیشتر مواقع با چند بررسی ساده می توان علت اصلی را پیدا کرد و مشکل را کامل حل کرد.

Static File در Django چیست؟

در Django فایل هایی مثل:

  • CSS
  • JavaScript
  • Font
  • تصویر

به عنوان Static File شناخته می شوند.

این فایل‌ها معمولا داخل پوشه‌هایی مثل static قرار می گیرند و وظیفه آن‌ها طراحی ظاهری سایت و اجرای بخش های فرانت اند است.

مثلا:

static/css/style.css
static/js/app.js

وقتی مرورگر نتواند این فایل ها را دریافت کند، ظاهر سایت به هم می ریزد یا بعضی قابلیت ها کار نمی کنند.

رایج‌ترین نشانه‌های مشکل Static File در Django

معمولا این مشکل با یکی از حالت‌های زیر خودش را نشان می‌دهد:

  • CSS لود نمی‌شود
  • تصاویر نمایش داده نمی‌شوند
  • پنل Admin بدون استایل باز می‌شود
  • خطای 404 برای فایل های static دیده می‌شود
  • JavaScript اجرا نمی شود

مثلا در Console مرورگر چنین خطایی دیده می‌شود:

GET /static/css/style.css 404

یا:

Refused to apply style

چرا Static File ها در Django لود نمی‌شوند؟

دلایل مختلفی وجود دارد اما چند مورد از بقیه رایج‌تر هستند.

تنظیم نبودن STATIC_URL

یکی از ابتدایی ترین مشکلات این است که STATIC_URL داخل فایل settings.py تنظیم نشده باشد.

نمونه درست:

STATIC_URL = '/static/'

اگر این مقدار اشتباه باشد، Django مسیر فایل ها را پیدا نمی‌کند.

تعریف نکردن STATICFILES_DIRS

وقتی فایل‌های Static داخل پوشه سفارشی قرار دارند، باید مسیر آن‌ها مشخص شود.

مثلا:

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

اگر این بخش تعریف نشود، Django فایل ها را شناسایی نمی‌کند.

فراموش کردن load static

این مورد خیلی رایج است؛ مخصوصا برای افراد تازه کار.

داخل Template باید این خط وجود داشته باشد:

{% load static %}

بعد فایل‌ها اینطوری فراخوانی شوند:

<link rel="stylesheet" href="{% static 'css/style.css' %}">

بعضی افراد مستقیم مسیر می‌دهند:

<link rel="stylesheet" href="/static/css/style.css">

این روش در بعضی شرایط مشکل ایجاد می‌کند.

اجرا نکردن collectstatic در سرور

در محیط Production فقط قرار دادن فایل‌ها داخل پوشه static کافی نیست.

باید دستور زیر اجرا شود:

python manage.py collectstatic

این دستور همه فایل‌های Static را داخل پوشه نهایی جمع آوری می‌کند.

اگر این مرحله انجام نشود، فایل‌ها روی سرور لود نمی‌شوند.

تنظیم نبودن STATIC_ROOT

وقتی از collectstatic استفاده می کنید، باید STATIC_ROOT هم مشخص باشد.

نمونه صحیح:

STATIC_ROOT = BASE_DIR / "staticfiles"

اگر این مقدار تعریف نشده باشد، collectstatic درست کار نمی‌کند.

مشکل در تنظیمات Nginx یا Apache

خیلی وقت‌ها Django کاملا درست تنظیم شده اما وب سرور فایل ها را سرو نمی‌کند.

مثلا در Nginx باید چنین بخشی وجود داشته باشد:

location /static/ {
    alias /home/project/staticfiles/;
}

اگر مسیر اشتباه باشد، همه فایل ها 404 می شوند.

تفاوت محیط Development و Production

در حالت Development، Django خودش فایل های Static را مدیریت می‌کند.

اما در Production این وظیفه معمولا بر عهده:

  • Nginx
  • Apache
  • CDN

است.

به همین دلیل پروژه‌ای که روی سیستم شخصی درست کار می‌کند، ممکن است روی سرور کامل خراب شود.

مشکل Debug=False

وقتی این مقدار فعال باشد:

DEBUG = False

دیگر Django فایل‌های Static را مستقیم سرو نمی‌کند.

خیلی از افراد این تغییر را اعمال می کنند اما تنظیمات Production را کامل انجام نمی‌دهند.

در نتیجه ظاهر سایت به هم می ریزد.

رایج‌ترین اشتباهات برنامه نویسان

قرار دادن static داخل App اشتباه

ساختار صحیح معمولا این شکلی است:

project/
    static/
        css/
        js/

یا:

app/
    static/
        app/

اما بعضی افراد فایل‌ها را در مسیر اشتباه قرار می دهند و Django آن ها را پیدا نمی‌کند.

استفاده اشتباه از مسیر فایل ها

این اشتباه خیلی دیده می‌شود:

src="static/image.png"

در حالی که باید از template tag استفاده شود:

src="{% static 'image.png' %}"

کش شدن فایل‌های قدیمی

گاهی فایل جدید آپلود شده اما مرورگر نسخه قبلی را Cache کرده است.

در این شرایط:

  • مرورگر را Hard Refresh کنید
  • Cache را پاک کنید
  • Incognito تست بگیرید

روش اصولی بررسی مشکل Static File

مرحله اول: بررسی Console مرورگر

اول DevTools مرورگر را باز کنید.

اگر خطای 404 وجود دارد یعنی فایل پیدا نشده است.

این مرحله خیلی کمک می کند سریع متوجه شوید مشکل از مسیر فایل هاست یا تنظیمات سرور.

مرحله دوم: تست مستقیم آدرس فایل

مثلا این آدرس را مستقیم داخل مرورگر باز کنید:

http://127.0.0.1:8000/static/css/style.css

اگر فایل باز نشد یعنی مسیر اشتباه است.

مرحله سوم: بررسی تنظیمات settings.py

این بخش‌ها را چک کنید:

STATIC_URL = '/static/'

STATICFILES_DIRS = [
    BASE_DIR / "static",
]

STATIC_ROOT = BASE_DIR / "staticfiles"

خیلی وقت ها فقط یک اشتباه کوچک داخل مسیرها وجود دارد.

مرحله چهارم: اجرای collectstatic

روی سرور همیشه این دستور را اجرا کنید:

python manage.py collectstatic

بعد مطمئن شوید فایل ها داخل staticfiles ساخته شده اند.

مرحله پنجم: بررسی وب سرور

اگر از Nginx استفاده می کنید، alias را بررسی کنید.

بعد سرویس را ریستارت کنید:

sudo systemctl restart nginx

بهترین روش مدیریت Static File در Django

ساختار پروژه را تمیز نگه دارید

پوشه‌های CSS و JS را جدا کنید.

مثلا:

static/
    css/
    js/
    images/

این کار مدیریت پروژه را راحت‌تر می‌کند.

از WhiteNoise استفاده کنید

برای پروژه‌های کوچک و متوسط، WhiteNoise خیلی کاربردی است.

نصب:

pip install whitenoise

بعد داخل Middleware اضافه کنید:

MIDDLEWARE = [
    'whitenoise.middleware.WhiteNoiseMiddleware',
]

این ابزار کمک می‌کند Django فایل های Static را راحت‌تر مدیریت کند.

فایل‌های اضافی را حذف کنید

بعضی پروژه ها بعد از مدتی پر از فایل های بدون استفاده می‌شوند.

این موضوع:

  • سرعت پروژه را کم می‌کند
  • Deploy را سنگین می‌کند
  • مدیریت فایل ها را سخت می‌کند

از CDN برای پروژه‌های بزرگ استفاده کنید

در پروژه‌های سنگین بهتر است فایل های Static از CDN سرو شوند.

این کار:

  • سرعت سایت را بیشتر می‌کند
  • فشار سرور را کم می‌کند
  • تجربه کاربر را بهتر می‌کند

جمع بندی

مشکل Static File در Django معمولا به خاطر تنظیمات اشتباه مسیرها، اجرا نکردن collectstatic یا پیکربندی نادرست وب سرور ایجاد می‌شود. اگر مسیر فایل‌ها، تنظیمات settings.py و تنظیمات Nginx را اصولی بررسی کنید، بیشتر این مشکلات خیلی سریع حل می‌شوند. مهم ترین نکته این است که تفاوت محیط Development و Production را به درستی درک کنید.