1. 开发环境准备
1.1 PyCharm专业版安装
作为Python开发的主流IDE,PyCharm专业版对Django框架提供了开箱即用的支持。建议从JetBrains官网下载最新版本(当前为2023.2),安装时注意勾选"Add launchers dir to the PATH"选项以便终端调用。专业版相比社区版额外提供了数据库工具、远程开发等对Django开发至关重要的功能模块。
注意:社区版虽然免费但缺少Django项目模板和数据库工具集成,开发效率会大打折扣
安装完成后首次启动时,建议进行以下基础配置:
- 在Preferences > Editor > Font中设置等宽字体(推荐Fira Code Retina)
- 在Preferences > Tools > Terminal修改默认Shell为系统常用终端(如zsh)
- 安装必备插件:Django、Database Navigator、Rainbow Brackets
1.2 Python环境配置
推荐使用pyenv管理多版本Python环境,避免系统Python被污染。以下是具体操作步骤:
bash复制# 安装pyenv(MacOS示例)
brew install pyenv
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zshrc
# 安装指定Python版本
pyenv install 3.10.6
pyenv global 3.10.6
# 验证安装
python -V # 应显示3.10.6
在PyCharm中配置解释器:
- 打开Preferences > Project: <your_project> > Python Interpreter
- 点击齿轮图标选择Add Interpreter > Add Local Interpreter
- 选择Existing environment并指向pyenv创建的Python路径(通常在~/.pyenv/versions下)
2. 创建Django项目
2.1 项目初始化
在PyCharm欢迎界面点击New Project,选择左侧的Django模板。关键配置项说明:
- Location:建议路径格式为~/Projects/<project_name>
- Python interpreter:选择之前配置的3.10.6解释器
- Django project settings:
- Application name:保持默认(后续可添加更多app)
- Templates folder:勾选以创建模板目录
- Enable Django admin:必选(后续后台管理依赖此功能)
点击Create后,PyCharm会自动完成以下工作:
- 创建标准的Django项目结构
- 生成manage.py和初始settings.py
- 安装django包及其依赖
- 配置Django支持(识别Django模板语法等)
2.2 项目结构解析
生成的标准目录结构及其作用:
code复制myproject/
├── manage.py # 项目管理脚本
├── myproject/ # 主项目包
│ ├── __init__.py
│ ├── asgi.py # ASGI配置(异步支持)
│ ├── settings.py # 核心配置文件
│ ├── urls.py # 主路由配置
│ └── wsgi.py # WSGI配置(生产部署)
└── templates/ # 全局模板目录
经验:不要在项目根目录直接放置.py文件,这会导致模块导入混乱。所有业务代码应放在app目录中。
3. 基础配置优化
3.1 设置文件拆分
默认的settings.py随着项目扩大会变得臃肿,建议拆分为:
code复制settings/
├── __init__.py # 从该文件导入配置
├── base.py # 通用配置
├── development.py # 开发环境配置
└── production.py # 生产环境配置
拆分步骤:
- 创建settings目录并移动原settings.py到base.py
- 在
__init__.py中添加:python复制from .development import * - 创建development.py:
python复制from .base import * DEBUG = True ALLOWED_HOSTS = ['localhost', '127.0.0.1'] - 修改manage.py和wsgi.py中的
os.environ.setdefault()指向新路径
3.2 数据库配置
Django默认使用SQLite,开发阶段可以保留,但建议提前配置PostgreSQL:
python复制# settings/base.py
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'mydatabase',
'USER': 'myuser',
'PASSWORD': 'mypassword',
'HOST': 'localhost',
'PORT': '5432',
}
}
安装依赖:
bash复制pip install psycopg2-binary
注意:生产环境务必使用完整的psycopg2而非binary版本
4. 开发工作流配置
4.1 运行配置优化
PyCharm默认创建的Django运行配置可能需要调整:
- 打开Run/Debug Configurations
- 选择Django Server配置
- 关键参数:
- Environment variables:添加
DJANGO_SETTINGS_MODULE=myproject.settings.development - Additional options:
--noreload(调试时禁用自动重载) - Python interpreter:确认选择正确版本
- Environment variables:添加
4.2 调试技巧
利用PyCharm强大的调试功能:
- 断点调试:在代码左侧点击设置断点,Debug模式启动项目
- Django模板调试:在Templates设置中启用"Don't check modification times"
- 控制台工具:
- Python Console:自动加载Django环境(需配置)
- Django Console:直接执行manage.py命令
配置Django环境控制台:
- 打开Preferences > Build, Execution, Deployment > Console > Django Console
- 添加环境变量:
python复制import os; os.environ['DJANGO_SETTINGS_MODULE'] = 'myproject.settings.development' - 添加路径:
python复制import sys; sys.path.extend(['${PROJECT_DIR}'])
5. 常见问题排查
5.1 启动报错处理
问题1:ModuleNotFoundError: No module named 'django'
- 原因:虚拟环境未正确配置
- 解决:
- 检查PyCharm右下角解释器选择
- 在Terminal执行
pip install django
问题2:TemplateDoesNotExist
- 原因:模板路径未正确配置
- 解决:
- 在settings.py中检查TEMPLATES['DIRS']
- 确保路径格式为
os.path.join(BASE_DIR, 'templates')
5.2 数据库迁移问题
问题1:表已存在错误
bash复制django.db.utils.ProgrammingError: relation "auth_user" already exists
- 解决:
bash复制
python manage.py migrate --fake
问题2:迁移文件冲突
- 解决:
- 查找冲突的迁移文件
- 执行:
bash复制
python manage.py makemigrations --merge
6. 项目最佳实践
6.1 代码组织规范
推荐的项目结构:
code复制myproject/
├── apps/ # 自定义应用
│ └── accounts/ # 示例应用
├── static/ # 静态文件
├── requirements/ # 依赖管理
│ ├── base.txt
│ ├── dev.txt
│ └── prod.txt
└── utils/ # 公共工具
创建新应用的正确方式:
bash复制# 在项目根目录执行(确保manage.py同级)
python manage.py startapp accounts
# 将应用移动到apps目录
mv accounts apps/
6.2 依赖管理
使用requirements文件分层管理:
bash复制# base.txt
Django==4.2.3
psycopg2==2.9.6
# dev.txt
-r base.txt
ipdb==0.13.11
django-debug-toolbar==3.8.1
# prod.txt
-r base.txt
gunicorn==20.1.0
安装开发依赖:
bash复制pip install -r requirements/dev.txt
7. 进阶配置
7.1 静态文件处理
开发模式配置:
python复制# settings/development.py
STATIC_URL = '/static/'
STATICFILES_DIRS = [os.path.join(BASE_DIR, 'static')]
生产环境配置:
python复制# settings/production.py
STATIC_ROOT = '/var/www/myproject/static'
收集静态文件:
bash复制python manage.py collectstatic
7.2 安全加固
必须修改的基础安全配置:
python复制# settings/base.py
SECRET_KEY = '从环境变量获取' # 实际使用os.environ.get()
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_BROWSER_XSS_FILTER = True
警告:永远不要将SECRET_KEY提交到版本控制系统!使用python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'生成新密钥
8. 部署准备
8.1 生产环境配置
关键差异配置:
python复制# settings/production.py
from .base import *
DEBUG = False
ALLOWED_HOSTS = ['yourdomain.com']
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': os.environ.get('DB_NAME'),
# 其他参数从环境变量获取...
}
}
8.2 WSGI配置
修改wsgi.py以支持多环境:
python复制import os
from django.core.wsgi import get_wsgi_application
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings.production')
application = get_wsgi_application()
建议使用Gunicorn作为WSGI服务器:
bash复制gunicorn --bind 0.0.0.0:8000 myproject.wsgi
9. 开发效率技巧
9.1 模板快捷操作
- 快速创建模板:右键templates目录 > New > Django Template
- 模板语法补全:输入
{%后按Tab自动补全语法结构 - 模板继承提示:在子模板顶部输入
{% extends时,PyCharm会显示可用父模板
9.2 代码实时检查
启用Django模板语言检查:
- 打开Preferences > Languages & Frameworks > Django
- 勾选"Enable Django Template language"
- 设置模板目录路径
配置PEP8检查:
- 安装flake8:
pip install flake8 - 在Preferences > Tools > External Tools中添加flake8检查
- 设置参数:
--max-line-length=120 --exclude=migrations
10. 项目维护建议
10.1 迁移管理策略
- 为每个功能分支创建独立迁移文件
- 定期使用
python manage.py squashmigrations压缩迁移 - 重要数据迁移使用
RunPython而非纯SQL
10.2 文档规范
推荐文档结构:
code复制docs/
├── api/ # API文档
├── dev_guide/ # 开发指南
├── setup.md # 环境配置
└── adr/ # 架构决策记录
使用mkdocs生成文档网站:
bash复制pip install mkdocs
mkdocs new .