Django 全栈开发与部署防坑手册（通用版）

适用：Django + Django REST Framework 后端 + 任意前端（Vue3 / uni-app / React）+ Linux 服务器部署。

这套经验从真实短剧平台的数月开发中提炼，已剥离具体项目信息（服务器、路径、模块名、API），只保留跨项目通用的方法论。

适用场景

• 开发/修改 Django 后端 API（model / serializer / view / url）
• 修改管理端或用户端前端页面
• 部署到 Linux 服务器（SFTP 上传 → migrate → 重启 → 验证）
• 排查 API 500、端口占用、迁移失败、中文乱码、页面样式问题

一、Windows 环境铁律（每条都真实踩过）

1. PowerShell 必须 UTF-8：每条 exec 起手 $utf8 = [System.Text.UTF8Encoding]::new($false); chcp 65001 > $null，中文输出乱码是红线。
2. Python 中文/emoji 输出报错：脚本内 print emoji 会 GBK 报错 → 设 $env:PYTHONIOENCODING='utf-8'（必要时加 $env:PYTHONUTF8='1'），或脚本内避免 emoji。
3. CRLF 行尾文件：edit 工具精确匹配会失败 → 改用 Python 脚本 io.open(encoding='utf-8') 做 replace/正则替换。
4. PowerShell 内嵌引号 / ||：多命令脚本里的 || 会解析报错、python -c "含引号" 会出错 → 一律改用独立 Python 脚本文件执行。
5. Windows tar 打包：Git GNU tar 不支持盘符路径（tar resolve failed）→ 用 Python tarfile 脚本打包。
6. 删除文件被安全策略拦截 → 一律 Move-Item 到 _backup/ 代替 rm（trash 优于 rm，可恢复）。

核心心法：「先写脚本文件再执行，别用 PowerShell 内联命令」——内联引号/中文/管道是最高频翻车点。

二、Django 开发流程

1. 读需求 → 定位改动点（后端 model/serializer/view/url + 前端页面）
2. 后端：改 model → 手写迁移（见下）→ serializer → view → url → django shell / py_compile 验证
3. 前端：改页面 → 构建（跳过 type-check 若历史遗留错误）→ 产物 grep 验证
4. 验证：本地 ast.parse / py_compile / manage.py check + 构建产物 + Playwright 页面测试
5. 部署：见下方部署 SOP

三、Django 迁移坑（最容易出事的环节）

• 迁移漂移坑：makemigrations 会自动生成大量无关 Alter（历史遗留），不能直接用。方案：makemigrations --empty 生成骨架 → 手写 CreateModel/AddField → 混合迁移移到备份目录。
• 纯 AddField 迁移：纯增量迁移必须只含 AddField，不能 RemoveField/RenameField（会因字段不存在报 KeyError）。
• 迁移链断裂：历史遗留迁移依赖不存在的父迁移 → 部署 migrate 会撞它，先诊断依赖链再动。
• tasks.py vs tasks/ 目录歧义：Python 导入目录优先于同名文件，旧 tasks/ 目录会遮蔽新 tasks.py。部署 celery 任务时注意。
• auto_now 字段：save() 会覆盖该字段，验证数据用 queryset.update() 绕过。
• 用 references/django-migrations.md 里的 deploy_helper.py diagnose 命令排查依赖链断裂。

四、部署 SOP（标准流程）

1. 备份：tar 备份目标目录（前端 dist、后端 apps）到 backups/，带时间戳。
2. SFTP 上传：先建远端目录树（rm -rf 后直接 put 会 FileNotFoundError），再传文件覆盖。
3. 后端迁移：python manage.py migrate <app> <number> --settings=...
4. 重启进程：见 assets/daphne_config.txt。⚠️ 旧进程占用端口会无声失败 → 先 ps aux 找进程 kill 再重启（日志 Address already in use = 端口被占）。
5. 验证：API curl 200 + 页面 200 + 资源 0 缺失 + Playwright 截图/实测。

五、验证方法

• 颜色对比度实测：必须用 Playwright getComputedStyle，别信视觉模型估色。
• 前端暗色主题变量：写页面前先确认全局 CSS 变量名（--text 系列），别用不存在的变量（如 --text1）。
• 登录按钮文本有空格：Playwright 匹配 has_text='登录' 会失败，直接点唯一 button。
• 浏览器工具 SSRF 拦外网 → 用 Playwright 本地脚本验证页面。
• 详见 references/verification.md。

六、资源

• references/windows-pitfalls.md — Windows 环境坑详解 + 脚本模板
• references/django-migrations.md — Django 迁移坑详解 + 诊断方法
• references/deployment-sop.md — 通用部署流程 + 历史事故复盘
• references/verification.md — Playwright 验证要点
• scripts/deploy_helper.py — 打包（tarfile）+ 迁移依赖链诊断
• scripts/verify_deploy.py — 部署后 API/页面 curl 验证（可传参）
• assets/daphne_config.txt — daphne / gunicorn 启动 + nginx 配置模板

当需要具体命令或事故细节时，读取对应 reference 文件。