Django入门教程（三）：django-admin与manage.py命令完全指南

一、django-admin 与 manage.py 的关系

在上一篇中，我们使用 django-admin startproject mysite 创建了项目，又用 python manage.py runserver 启动了服务器。很多初学者会困惑：这两个命令有什么区别？该用哪一个？

简单来说：

对比项	django-admin	manage.py
本质	Django 全局命令行工具	项目自动生成的管理脚本
位置	Python 安装目录的 Scripts 下	项目根目录下
作用范围	可操作任意 Django 项目	仅作用于当前项目
推荐场景	创建项目（startproject）	项目内所有操作（迁移、运行、测试等）

manage.py 本质上是对 django-admin 的一层封装，它在执行命令前会自动设置 DJANGO_SETTINGS_MODULE 环境变量，指向当前项目的 settings.py。因此，在项目内部进行操作时，始终推荐使用 python manage.py <命令> ；只有在创建新项目时，才使用 django-admin startproject。

你可以把 django-admin 理解为"全局工具"，把 manage.py 理解为"项目专属工具"。

二、查看所有可用命令

要查看 django-admin 提供的所有命令，运行：

django-admin help

输出内容类似如下：

Type 'django-admin help <subcommand>' for help on a specific subcommand.

Available subcommands:

[django]
    check
    compilemessages
    createcachetable
    dbshell
    diffsettings
    dumpdata
    flush
    inspectdb
    loaddata
    makemessages
    makemigrations
    migrate
    optimizemigration
    runserver
    sendtestemail
    shell
    showmigrations
    sqlflush
    sqlmigrate
    sqlsequencereset
    squashmigrations
    startapp
    startproject
    test
    testserver
    ...

如果想查看某个具体命令的帮助信息，可以使用：

django-admin help <子命令>
# 例如
django-admin help startproject
python manage.py help migrate

三、常用命令速查表

下表汇总了开发过程中最高频的命令，后续章节会逐一详解：

命令	作用	示例
startproject	创建一个新 Django 项目	django-admin startproject myproject
startapp	创建一个新 Django 应用	python manage.py startapp myapp
runserver	启动开发服务器	python manage.py runserver
makemigrations	生成数据库迁移文件	python manage.py makemigrations
migrate	执行数据库迁移	python manage.py migrate
createsuperuser	创建管理员账号	python manage.py createsuperuser
shell	启动 Django 交互式 Shell	python manage.py shell
collectstatic	收集静态文件（生产环境）	python manage.py collectstatic
test	运行单元测试	python manage.py test
check	检查项目配置	python manage.py check

四、核心命令详解

1. startproject ------ 创建新项目

基本语法：

django-admin startproject <项目名称> [目标目录]

参数说明：

参数	作用	示例
<项目名称>	必填，项目名称（会生成同名目录）	django-admin startproject mysite
[目标目录]	可选，指定项目存放目录	django-admin startproject mysite /opt/myproject
--template	使用自定义项目模板	django-admin startproject --template=my_template.zip mysite
--extension	指定文件扩展名	django-admin startproject --extension=py,txt mysite
--name	指定文件名模式	django-admin startproject --name=Dockerfile mysite

实例：

# 创建默认项目
django-admin startproject mysite

# 指定目录创建
django-admin startproject mysite /opt/code

# 使用远程模板创建
django-admin startproject --template=https://example.com/my_template.zip mysite

执行 startproject 后，生成的目录结构如下：

mysite/
├── manage.py
└── mysite/
    ├── __init__.py
    ├── settings.py
    ├── urls.py
    └── wsgi.py

2. startapp ------ 创建新应用

基本语法：

python manage.py startapp <应用名称> [目标目录]

参数说明：

参数	作用	示例
<应用名称>	必填，应用名称	python manage.py startapp blog
[目标目录]	可选，指定应用存放目录	python manage.py startapp blog /opt/myapp
--template	使用自定义应用模板	python manage.py startapp --template=my_app_template.zip blog

实例：

# 创建默认应用
python manage.py startapp blog

# 指定目录创建
python manage.py startapp blog /opt/myapp

# 使用模板创建
python manage.py startapp --template=my_template.zip blog

创建后的应用结构：

blog/
├── migrations/
│   └── __init__.py
├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── tests.py
└── views.py

提醒： 创建应用后，记得在 settings.py 的 INSTALLED_APPS 中注册该应用，否则 Django 不会识别它。

3. runserver ------ 启动开发服务器

基本语法：

python manage.py runserver [IP:端口]

参数说明：

参数	作用	示例
[IP:端口]	指定监听的 IP 和端口（默认 127.0.0.1:8000）	python manage.py runserver 0.0.0.0:8080
--noreload	禁用自动重载（调试时使用）	python manage.py runserver --noreload
--insecure	强制静态文件服务（非 DEBUG 模式）	python manage.py runserver --insecure

实例：

# 默认启动
python manage.py runserver

# 允许外部访问（同一局域网内其他设备可访问）
python manage.py runserver 0.0.0.0:8000

# 仅修改端口
python manage.py runserver 8080

4. makemigrations 与 migrate ------ 数据库迁移

Django 使用迁移系统来管理数据库模式的变更。这两个命令通常成对使用：

# 1. 根据模型变化生成迁移文件
python manage.py makemigrations

# 2. 将迁移应用到数据库
python manage.py migrate

migrate 命令参数详解：

基本语法：

python manage.py migrate [应用名] [迁移版本]

参数	作用	示例
[应用名]	指定要迁移的应用	python manage.py migrate blog
[迁移版本]	指定迁移版本号	python manage.py migrate blog 0002
--fake	标记迁移为已执行（不实际修改数据库）	python manage.py migrate --fake
--fake-initial	仅当表已存在时标记为已执行	python manage.py migrate --fake-initial

实例：

# 执行所有未应用的迁移
python manage.py migrate

# 仅迁移 blog 应用
python manage.py migrate blog

# 迁移到特定版本
python manage.py migrate blog 0002

补充： makemigrations 命令还有一个实用参数 --name，可以为迁移文件指定一个易读的名称：

bash

python manage.py makemigrations blog --name add_author_field

5. createsuperuser ------ 创建管理员

python manage.py createsuperuser

执行后会交互式地提示你输入用户名、邮箱和密码。创建成功后，即可通过 /admin/ 登录 Django 管理后台。

6. shell ------ 交互式调试

python manage.py shell

这会启动一个带有 Django 上下文的 Python 交互式环境，你可以直接导入模型并进行 ORM 查询：

>>> from blog.models import Article
>>> Article.objects.all()
<QuerySet []>
>>> Article.objects.create(title="Hello", content="Django shell test")
<Article: Article object (1)>

7. check ------ 检查项目配置

python manage.py check

该命令会检查项目配置是否存在错误，包括模型定义、URL 配置、模板设置、静态文件配置等。在部署前运行一次，可以提前发现潜在问题。

8. collectstatic ------ 收集静态文件

python manage.py collectstatic

将各个应用中的静态文件收集到 STATIC_ROOT 指定的目录，用于生产环境部署（通常由 Nginx 等 Web 服务器直接提供服务）。

五、其他实用命令

命令	作用	示例
test	运行测试用例	python manage.py test blog
dbshell	进入数据库命令行	python manage.py dbshell
showmigrations	查看迁移状态	python manage.py showmigrations
sqlmigrate	查看迁移对应的 SQL 语句	python manage.py sqlmigrate blog 0001
dumpdata	导出数据库数据为 JSON	python manage.py dumpdata blog > blog.json
loaddata	导入数据	python manage.py loaddata blog.json
flush	清空数据库（保留表结构）	python manage.py flush
diffsettings	查看当前设置与默认设置的差异	python manage.py diffsettings

六、常见问题与技巧

1. 命令执行报错 "No module named 'xxx'"

通常是因为应用未在 INSTALLED_APPS 中注册，或者当前目录不在 manage.py 所在目录。确保在项目根目录执行命令。

2. 如何查看某个命令的详细帮助？

python manage.py help <命令名>
# 或
python manage.py <命令名> --help

3. 如何一次性执行多个命令？

可以编写 Shell 脚本或使用 && 串联：

python manage.py makemigrations && python manage.py migrate

4. --fake 的使用场景

当你手动修改了数据库表结构，但希望 Django 认为迁移已执行时使用。慎用，否则可能导致数据库与迁移记录不一致。

七、小结

本篇系统梳理了 django-admin 和 manage.py 的核心命令。你现在应该能够熟练地：

• 创建项目与应用

• 启动开发服务器

• 管理数据库迁移

• 创建管理员账号

• 使用 Shell 进行交互式调试

这些命令将贯穿你整个 Django 开发生涯。建议把常用命令整理成笔记或 Shell 别名，能显著提升开发效率。下一篇我们将深入 Model 模型层，学习如何用 Python 类定义数据库表，并利用 ORM 完成增删改查。