راهنمای کامل manage.py

manage.py یک ابزار خط فرمان در جنگو است که مدیریت پروژه را از ساخت اپلیکیشن تا اجرای سرور توسعه ممکن می‌کند. این فایل در ریشه هر پروژه جنگو قرار دارد و با دستورات متنوع، چرخه توسعه را ساده می‌سازد. در این راهنما، تمام دستورات manage.py را با مثال‌های عملی بررسی می‌کنیم. از runserver و migrate تا دستورات سفارشی و مدیریت فایل‌های استاتیک. هدف این است که با تسلط بر manage.py، بهره‌وری توسعه جنگو را به‌طور چشمگیری افزایش دهید.

در نخستین مواجهه با یک پروژه جنگو، فایل manage.py مانند یک جعبه جادویی به نظر می‌رسد. هر کاری که برای مدیریت پروژه لازم است، از اجرای سرور تا ساخت دیتابیس، از طریق این فایل انجام می‌شود. در این راهنما، تجربه‌های عملی از کار با این ابزار را به‌صورت ساختاریافته ارائه می‌کنیم.

manage.py چیست و چرا اهمیت دارد؟

manage.py یک اسکریپت پایتون است که در ریشه هر پروژه جنگو قرار دارد و به‌عنوان نقطه ورود خط فرمان (Command-Line Entry Point) عمل می‌کند. این فایل در واقع یک wrapper نازک вокруг django-admin است که تنظیمات پروژه را بارگذاری می‌کند و سپس دستورات را به موتور مدیریت جنگو می‌سپارد. بدون manage.py، هر بار باید متغیر محیطی DJANGO_SETTINGS_MODULE را تنظیم کنید و از django-admin مستقیم استفاده کنید، که کار را دشوار می‌کند.

اهمیت manage.py در چند چیز خلاصه می‌شود:

مدیریت متمرکز پروژه از طریق یک فایل
دسترسی به تمام دستورات داخلی جنگو
امکان تعریف دستورات سفارشی (Custom Management Commands)
اجرای سرور توسعه، مهاجرت‌ها، تست‌ها و بسیاری از وظایف دیگر

اگر تازه با جنگو آشنا شده‌اید، پیشنهاد می‌کنم ابتدا آموزش جنگو برای مبتدیان را مطالعه کنید تا درک بهتری از ساختار پروژه پیدا کنید.

«manage.py پل ارتباطی بین توسعه‌دهنده و اکوسیستم جنگو است. هرچه این پل را بهتر بشناسید، توسعه سریع‌تر و لذت‌بخش‌تر می‌شود.»

ساختار و نحوه کار manage.py

وقتی پروژه جدیدی با دستور django-admin startproject mysite می‌سازید، فایل manage.py به‌طور خودکار در پوشه پروژه ایجاد می‌شود. محتوای این فایل معمولاً به این شکل است:

#!/usr/bin/env python
import os
import sys

if __name__ == "__main__":
    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")
    try:
        from django.core.management import execute_from_command_line
    except ImportError as exc:
        raise ImportError(
            "Couldn't import Django. Are you sure it's installed and "
            "available on your PYTHONPATH environment variable? Did you "
            "forget to activate a virtual environment?"
        ) from exc
    execute_from_command_line(sys.argv)

این فایل دو کار اصلی انجام می‌دهد:

تنظیم متغیر محیطی DJANGO_SETTINGS_MODULE به ماژول تنظیمات پروژه
فراخوانی execute_from_command_line که دستورات را پردازش می‌کند

نکته مهم این است که manage.py همیشه باید در ریشه پروژه اجرا شود. اگر در پوشه دیگری باشید، جنگو نمی‌تواند ماژول تنظیمات را پیدا کند و خطا می‌دهد.

دستورات پرکاربرد manage.py

دستورات manage.py به دو دسته کلی تقسیم می‌شوند: دستورات داخلی جنگو و دستورات سفارشی که خودتان می‌سازید. در ادامه، مهم‌ترین دستورات داخلی را با مثال بررسی می‌کنیم.

1. runserver – اجرای سرور توسعه

پرکاربردترین دستور برای اجرای پروژه در محیط توسعه:

python manage.py runserver

به‌طور پیش‌فرض، سرور روی 127.0.0.1:8000 اجرا می‌شود. می‌توانید پورت را تغییر دهید:

python manage.py runserver 8080

یا آدرس IP خاصی را bind کنید:

python manage.py runserver 0.0.0.0:8000

هشدار: هرگز از runserver در محیط تولید استفاده نکنید. این سرور فقط برای توسعه طراحی شده و امنیت و کارایی لازم را ندارد.

2. migrate – اعمال مهاجرت‌های دیتابیس

برای اعمال تغییرات مدل‌ها به دیتابیس:

python manage.py migrate

برای مشاهده وضعیت مهاجرت‌ها:

python manage.py showmigrations

برای بازگرداندن یک مهاجرت خاص:

python manage.py migrate app_name 0002

اگر با خطاهای مربوط به مهاجرت مواجه شدید، مقاله چگونه خطاهای رایج Django را سریع و اصولی رفع کنیم؟ را بخوانید.

3. makemigrations – ساخت فایل‌های مهاجرت

پس از تغییر مدل‌ها، باید فایل مهاجرت بسازید:

python manage.py makemigrations

برای یک اپ خاص:

python manage.py makemigrations myapp

برای مشاهده SQL تولیدشده بدون اجرا:

python manage.py sqlmigrate myapp 0001

4. startapp – ساخت اپلیکیشن جدید

python manage.py startapp blog

این دستور ساختار اولیه یک اپ جنگو را ایجاد می‌کند. سپس باید نام اپ را به INSTALLED_APPS در settings.py اضافه کنید.

5. startproject – ساخت پروژه جدید

اگرچه معمولاً از django-admin استفاده می‌شود، اما می‌توان با manage.py هم پروژه ساخت:

python manage.py startproject mynewproject

توجه: این دستور باید در پوشه‌ای اجرا شود که manage.py وجود ندارد، وگرنه خطا می‌دهد.

6. createsuperuser – ساخت کاربر ادمین

python manage.py createsuperuser

این دستور به‌صورت تعاملی نام کاربری، ایمیل و رمز عبور را می‌پرسد. برای ساخت غیرتعاملی:

python manage.py createsuperuser --username admin --email admin@example.com

7. shell – پوسته تعاملی جنگو

python manage.py shell

این دستور یک پوسته پایتون با تنظیمات جنگو باز می‌کند. برای اجرای یک اسکریپت:

python manage.py shell < script.py

یا استفاده از shell_plus از پکیج django-extensions که مدل‌ها را خودکار import می‌کند.

8. collectstatic – جمع‌آوری فایل‌های استاتیک

python manage.py collectstatic

این دستور تمام فایل‌های استاتیک اپ‌ها را در پوشه STATIC_ROOT کپی می‌کند. برای محیط تولید ضروری است.

9. test – اجرای تست‌ها

python manage.py test

برای اجرای تست‌های یک اپ خاص:

python manage.py test myapp

برای اجرای یک کلاس تست خاص:

python manage.py test myapp.tests.MyTestCase

10. check – بررسی سلامت پروژه

python manage.py check

این دستور خطاهای پیکربندی را بدون اجرای سرور بررسی می‌کند. برای بررسی دقیق‌تر:

python manage.py check --deploy

گزینه --deploy هشدارهای مربوط به محیط تولید را نشان می‌دهد.

دستور	کاربرد	مثال
`runserver`	اجرای سرور توسعه	`python manage.py runserver`
`migrate`	اعمال مهاجرت‌ها	`python manage.py migrate`
`makemigrations`	ساخت فایل مهاجرت	`python manage.py makemigrations`
`startapp`	ساخت اپ جدید	`python manage.py startapp blog`
`createsuperuser`	ساخت کاربر ادمین	`python manage.py createsuperuser`
`collectstatic`	جمع‌آوری فایل‌های استاتیک	`python manage.py collectstatic`

مدیریت دیتابیس با manage.py

جنگو دستورات متعددی برای مدیریت دیتابیس ارائه می‌دهد که همگی از طریق manage.py قابل اجرا هستند.

dbshell – اتصال به پوسته دیتابیس

python manage.py dbshell

این دستور شما را مستقیماً به پوسته دیتابیس (مثلاً PostgreSQL یا MySQL) متصل می‌کند. برای اجرای سریع کوئری‌ها عالی است.

dumpdata – خروجی گرفتن از داده‌ها

python manage.py dumpdata > backup.json

برای خروجی گرفتن از یک اپ خاص:

python manage.py dumpdata myapp > myapp_backup.json

فرمت‌های دیگر مانند XML و YAML نیز پشتیبانی می‌شوند.

loaddata – بارگذاری داده‌ها

python manage.py loaddata backup.json

این دستور داده‌ها را از فایل fixture بارگذاری می‌کند. برای تست‌ها و مهاجرت داده بسیار مفید است.

flush – پاک کردن دیتابیس

python manage.py flush

تمام داده‌ها را حذف می‌کند اما ساختار جداول باقی می‌ماند. با احتیاط استفاده کنید.

sqlflush – نمایش SQL پاک‌سازی

python manage.py sqlflush

SQL مربوط به flush را نمایش می‌دهد بدون اجرا.

برای مدیریت پیشرفته‌تر دیتابیس و بهینه‌سازی، مطالعه بهینه‌سازی عملکرد جنگو برای سایت پربازدید توصیه می‌شود.

مدیریت اپلیکیشن‌ها

هر پروژه جنگو از چندین اپلیکیشن تشکیل شده است. manage.py ابزارهای لازم برای مدیریت آن‌ها را فراهم می‌کند.

ساخت اپ جدید

python manage.py startapp shop

ساختار اپ شامل فایل‌های models.py، views.py، admin.py و غیره است.

حذف اپ

دستور مستقیمی برای حذف اپ وجود ندارد. باید اپ را از INSTALLED_APPS حذف کنید، پوشه آن را پاک کنید و مهاجرت‌های مربوطه را برگردانید.

مدیریت مهاجرت‌های اپ

python manage.py makemigrations shop
python manage.py migrate shop

اگر در طراحی مدل‌ها و جداسازی منطق کسب‌وکار به کمک نیاز دارید، مقاله services.py در جنگو: چرا منطق کسب‌وکار باید از ویو جدا شود؟ را ببینید.

مدیریت کاربران

مدیریت کاربران در جنگو از طریق manage.py بسیار ساده است.

ساخت کاربر ادمین

python manage.py createsuperuser

تغییر رمز عبور

python manage.py changepassword username

ساخت کاربر عادی با shell

python manage.py shell
>>> from django.contrib.auth.models import User
>>> User.objects.create_user("john", "john@example.com", "password123")

برای امنیت بیشتر کاربران، پیشنهاد می‌کنم امنیت در Django: بهترین روش‌ها را مطالعه کنید.

مدیریت فایل‌های استاتیک

فایل‌های استاتیک شامل CSS، JavaScript و تصاویر هستند. manage.py دو دستور اصلی برای این کار دارد.

collectstatic

python manage.py collectstatic

این دستور تمام فایل‌های استاتیک را از اپ‌ها و پوشه‌های اضافی به STATIC_ROOT کپی می‌کند. برای محیط تولید ضروری است.

گزینه --noinput برای عدم تأیید:

python manage.py collectstatic --noinput

findstatic

python manage.py findstatic style.css

مسیر فایل استاتیک را پیدا می‌کند. برای دیباگ مفید است.

تست و عیب‌یابی

جنگو ابزارهای قدرتمندی برای تست و عیب‌یابی دارد که همگی از طریق manage.py اجرا می‌شوند.

اجرای تست‌ها

python manage.py test

برای اجرای تست‌ها با پوشش:

coverage run manage.py test
coverage report

check – بررسی پروژه

python manage.py check

برای بررسی مشکلات امنیتی در تولید:

python manage.py check --deploy

diffsettings – مقایسه تنظیمات

python manage.py diffsettings

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

showmigrations – وضعیت مهاجرت‌ها

python manage.py showmigrations

اگر با خطای 404 در جنگو مواجه شدید، مقاله رفع خطای 404 در جنگو به دلیل تداخل URL catch-all با slug را بخوانید.

دستورات سفارشی

یکی از قدرتمندترین قابلیت‌های manage.py امکان تعریف دستورات سفارشی است. این کار به شما اجازه می‌دهد وظایف تکراری را خودکار کنید.

ساختار پوشه‌ها:

myapp/
    management/
        __init__.py
        commands/
            __init__.py
            my_custom_command.py

محتوای فایل my_custom_command.py:

from django.core.management.base import BaseCommand

class Command(BaseCommand):
    help = "My custom command"

    def add_arguments(self, parser):
        parser.add_argument("--name", type=str, help="Name to greet")

    def handle(self, *args, **options):
        name = options["name"] or "World"
        self.stdout.write(self.style.SUCCESS(f"Hello, {name}!"))

اجرا:

python manage.py my_custom_command --name Django

برای مدیریت بهتر منطق کسب‌وکار در دستورات سفارشی، پیشنهاد می‌کنم services.py در جنگو را مطالعه کنید.

manage.py در محیط تولید

در محیط تولید، استفاده از runserver ممنوع است. به‌جای آن از سرورهای WSGI مانند Gunicorn یا uWSGI استفاده کنید. اما manage.py همچنان برای کارهای نگهداری ضروری است.

اجرای مهاجرت‌ها در تولید

python manage.py migrate --noinput

جمع‌آوری فایل‌های استاتیک

python manage.py collectstatic --noinput

بررسی تنظیمات تولید

python manage.py check --deploy

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

خطاهای رایج و رفع آن‌ها

خطای ModuleNotFoundError

معمولاً به‌دلیل اجرای manage.py در پوشه اشتباه یا نبود پکیج موردنیاز رخ می‌دهد. مطمئن شوید در ریشه پروژه هستید و محیط مجازی فعال است.

خطای no such table

یعنی مهاجرت‌ها اعمال نشده‌اند. دستور python manage.py migrate را اجرا کنید.

خطای port already in use

پورت 8000 اشغال است. با python manage.py runserver 8080 پورت را تغییر دهید.

خطای DJANGO_SETTINGS_MODULE is not defined

فایل manage.py را از ریشه پروژه اجرا کنید.

برای فهرست کامل خطاها، مقاله چگونه خطاهای رایج Django را سریع و اصولی رفع کنیم؟ را ببینید.

پرسش‌های پرتکرار

آیا می‌توانم manage.py را تغییر نام دهم؟

بله، اما توصیه نمی‌شود. نام manage.py یک قرارداد است و تغییر آن ممکن است سایر توسعه‌دهندگان را گیج کند.

تفاوت manage.py و django-admin چیست؟

django-admin ابزار عمومی است و به تنظیمات پروژه وابسته نیست. manage.py تنظیمات پروژه را بارگذاری می‌کند و برای کار روی یک پروژه خاص طراحی شده است.

چگونه یک دستور سفارشی با آرگومان‌های پیچیده بسازم؟

از add_arguments و argparse استفاده کنید. مثال در بخش دستورات سفارشی آورده شد.

آیا می‌توانم manage.py را در کرون‌جاب استفاده کنم؟

بله، اما بهتر است از django-admin با تنظیم DJANGO_SETTINGS_MODULE استفاده کنید یا از celery برای تسک‌های زمان‌بندی‌شده بهره ببرید.

چگونه خروجی manage.py را در فایل ذخیره کنم؟

python manage.py dumpdata > backup.json

آیا manage.py در ویندوز کار می‌کند؟

بله، اما باید از python manage.py استفاده کنید، نه ./manage.py.

ملاحظات سطح ارشد

در سطح مهندسی ارشد، manage.py تنها یک ابزار خط فرمان نیست؛ بلکه یک نقطه ورود قابل توسعه است. می‌توانید فایل manage.py را سفارشی کنید تا تنظیمات پیش‌فرض را تغییر دهید، لاگ‌گیری اضافه کنید یا حتی دستورات را قبل از اجرا اعتبارسنجی کنید.

یکی از الگوهای پیشرفته، استفاده از manage.py برای اجرای اسکریپت‌های داده‌کاوی و پردازش دسته‌ای است. با ترکیب BaseCommand و argparse می‌توانید دستوراتی بسازید که به‌عنوان بخشی از خط لوله CI/CD اجرا شوند.

نکته کمتر شناخته‌شده: می‌توانید manage.py را طوری تنظیم کنید که به‌طور خودکار محیط مجازی را فعال کند. اگرچه این کار توصیه نمی‌شود، اما در محیط‌های توسعه خاص می‌تواند مفید باشد.

در پروژه‌های بزرگ، استفاده از manage.py برای اجرای تست‌های یکپارچگی (Integration Tests) با دیتابیس واقعی بسیار رایج است. با گزینه --keepdb می‌توانید از بازسازی دیتابیس تست در هر اجرا جلوگیری کنید و سرعت تست را به‌طور چشمگیری افزایش دهید.

python manage.py test --keepdb

همچنین برای پروژه‌هایی که از چند دیتابیس استفاده می‌کنند، می‌توانید با --database دیتابیس موردنظر را مشخص کنید:

python manage.py migrate --database=replica

در نهایت، برای بهینه‌سازی عملکرد دستورات مدیریتی، می‌توانید از --parallel در تست‌ها استفاده کنید:

python manage.py test --parallel

«تسلط بر manage.py تنها یک مهارت نیست؛ کلید ورود به اتوماسیون و مقیاس‌پذیری در جنگو است.»

نتیجه‌گیری

manage.py قلب تپنده مدیریت پروژه‌های جنگو است. از ساخت اپلیکیشن و مهاجرت دیتابیس تا اجرای تست‌ها و دستورات سفارشی، همه چیز از طریق این فایل انجام می‌شود. با یادگیری دستورات مختلف و نحوه سفارشی‌سازی آن‌ها، می‌توانید بهره‌وری خود را چند برابر کنید.

اگر تجربه‌ای از استفاده از دستورات خاص manage.py دارید یا با خطایی مواجه شده‌اید که راه‌حل جالبی برای آن پیدا کرده‌اید، خوشحال می‌شوم در دیدگاه‌ها بشنوم. به‌خصوص اگر راه‌حل خلاقانه‌ای برای اتوماسیون وظایف با manage.py دارید که می‌تواند برای سایر توسعه‌دهندگان مفید باشد.