Become a sponsor
常见问题FAQ
本章节整理了项目开发和部署过程中常见的问题及解决方案，帮助你快速定位和解决问题。
温馨提示
遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。
1. 端口被占用
现象
启动后端服务时报错：
OSError: [Errno 98] Address already in use或：
ERROR: [Errno 10048] 通常每个套接字地址(协议/网络地址/端口)只允许使用一次原因
端口 8000（或配置的其他端口）已被其他程序占用。
解决方案
bash
# Windows 查看端口占用
netstat -ano | findstr 8000
# 找到 PID 后终止进程
taskkill /PID <进程ID> /F
# Linux / macOS 查看端口占用
lsof -i :8000
# 终止进程
kill -9 <进程ID>或者使用其他端口启动：
bash
python manage.py runserver 8080温馨提示
前端开发服务器端口冲突同理，修改 ui/.env.development 中的 VITE_PORT 即可。
2. 数据库连接失败
现象
启动时报错：
pymysql.err.OperationalError: (2003, "Can't connect to MySQL server on '127.0.0.1'")或：
django.db.utils.OperationalError: (1045, "Access denied for user 'root'@'localhost'")排查步骤
1. 检查 MySQL 服务是否已启动
2. 检查 .env 中的 DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD 是否正确
3. 检查数据库用户是否有远程连接权限
4. 检查防火墙是否放行了数据库端口解决方案
bash
# 测试数据库连接
mysql -h127.0.0.1 -P3306 -uroot -p
# 如果是权限问题，授权用户
mysql -uroot -p
GRANT ALL PRIVILEGES ON `djangoadmin.django.elevue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;温馨提示
确认 .env 中的 DATABASE_PASSWORD 没有多余的空格或引号。密码中的特殊字符可能需要转义。
3. Redis 连接失败
现象
启动时报错：
redis.exceptions.ConnectionError: Error connecting to 127.0.0.1:6379或：
redis.exceptions.AuthenticationError: Authentication required排查步骤
1. 检查 Redis 服务是否已启动
2. 检查 .env 中的 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 是否正确
3. 检查 Redis 是否设置了密码解决方案
bash
# 测试 Redis 连接
redis-cli -h 127.0.0.1 -p 6379 -a your_password ping
# Windows 启动 Redis 服务
net start Redis
# Linux 启动 Redis 服务
sudo systemctl start redis
# macOS 启动 Redis 服务
brew services start redis温馨提示
Redis 用于存储验证码和 JWT 令牌黑名单，是项目正常运行的必需服务。确保 .env 中的 REDIS_PASSWORD 与 Redis 实际配置的密码一致。
4. pip install 安装失败
现象
执行 pip install -r requirements.txt 时报错：
ERROR: Could not find a version that satisfies the requirement xxx或：
ERROR: Failed building wheel for xxx解决方案
bash
# 方案一：使用国内镜像源
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
# 方案二：升级 pip 后重试
python -m pip install --upgrade pip
pip install -r requirements.txt
# 方案三：配置全局镜像源
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.comrequirements.txt 编码问题
requirements.txt 文件为 UTF-16LE 编码，部分系统可能无法正确解析。如果 pip install 报编码错误，请先将文件转换为 UTF-8：
bash
# Windows (PowerShell)
Get-Content requirements.txt -Encoding Unicode | Set-Content -Encoding UTF8 requirements_utf8.txt
pip install -r requirements_utf8.txt
# Linux / macOS
iconv -f UTF-16LE -t UTF-8 requirements.txt > requirements_utf8.txt
pip install -r requirements_utf8.txt5. mysqlclient 安装失败
现象
Windows 系统安装 mysqlclient 时报错：
error: Microsoft Visual C++ 14.0 or greater is required解决方案
bash
# 方案一：安装 Visual C++ Build Tools
# 下载地址：https://visualstudio.microsoft.com/visual-cpp-build-tools/
# 方案二：使用预编译的 wheel 包
# 访问 https://www.lfd.uci.edu/~gohlke/pythonlibs/#mysqlclient
# 下载对应版本的 .whl 文件后安装
# 方案三：使用 pymysql 作为替代（不推荐用于生产）
pip install pymysql6. pnpm install 安装失败
现象
执行 pnpm install 时报错：
ERR_PNPM_NO_MATCHING_VERSION或：
GET https://registry.npmjs.org/xxx error解决方案
bash
# 方案一：切换淘宝镜像源
pnpm config set registry https://registry.npmmirror.com
pnpm install
# 方案二：清除缓存后重试
pnpm store prune
rm -rf node_modules
pnpm install
# 方案三：使用 --shamefully-hoist 模式
pnpm install --shamefully-hoist温馨提示
如果网络环境受限，可以尝试使用 VPN 或配置代理：
bash
pnpm config set proxy http://127.0.0.1:7890
pnpm config set https-proxy http://127.0.0.1:78907. API 请求返回 404
现象
调用接口时返回：
html
<h1>Page not found (404)</h1>原因
可能是请求路径不正确，或后端路由未正确注册。
排查步骤
1. 检查请求路径是否正确（如 /login/captcha、/example/page）
2. 检查 application/urls.py 中是否注册了对应模块的路由
3. 检查前端代理配置中的后端地址是否正确解决方案
bash
# 测试后端服务是否正常
curl http://127.0.0.1:8000/login/captcha
# 检查前端代理配置
# ui/.env.development
VITE_PROXY=[["/api","http://127.0.0.1:8000/"]]温馨提示
前端所有以 /api 开头的请求会被代理到后端的 8000 端口。例如：
- 前端请求
http://localhost:8001/api/login/captcha - 会被代理到
http://127.0.0.1:8000/login/captcha
8. 验证码图片不显示
现象
登录页面验证码图片区域空白，或显示加载失败图标。
排查步骤
1. 打开浏览器控制台（F12），查看 Network 标签中的请求状态
2. 检查 /login/captcha 接口是否返回正常
3. 检查 Redis 服务是否正常（验证码存储在 Redis 中）解决方案
bash
# 1. 测试验证码接口
curl http://127.0.0.1:8000/login/captcha
# 2. 测试 Redis 连接
redis-cli -h 127.0.0.1 -p 6379 -a your_password ping
# 应返回 PONG
# 3. 检查 Django 验证码配置是否正常
python manage.py shell
>>> from captcha.models import CaptchaStore
>>> CaptchaStore.objects.count()温馨提示
验证码生成依赖 django-simple-captcha 库和 Pillow 库。如果验证码接口报错，请确认这两个库已正确安装。
9. 接口返回权限不足
现象
调用接口返回：
json
{
"code": 1,
"data": null,
"msg": "权限不足",
"ok": false
}原因
当前登录用户没有该接口的访问权限。项目采用 RBAC 权限模型，每个接口对应一个权限字符串（如 sys:user:list）。
解决方案
1. 使用 admin 账号登录（ID=1 的管理员绕过所有权限检查）
2. 检查当前用户的角色是否包含该接口的权限
3. 在系统管理 > 菜单管理中，确认接口对应的权限节点已正确配置
4. 在系统管理 > 角色管理中，确认角色已分配该权限温馨提示
admin 用户（ID=1）是超级管理员，拥有全部权限，不受权限检查限制。开发调试时建议使用 admin 账号。
10. 文件上传失败
现象
上传文件时返回错误：
json
{
"code": 1,
"data": null,
"msg": "文件上传失败",
"ok": false
}排查步骤
1. 检查上传目录是否存在且有写入权限
2. 检查 .env 中的 DJANGO_UPLOAD_DIR 配置是否正确
3. 检查 .env 中的 DJANGO_FILE_URL 配置是否正确
4. 检查文件大小是否超过 Django 的 FILE_UPLOAD_MAX_MEMORY_SIZE 限制解决方案
bash
# .env 中的上传配置
DJANGO_UPLOAD_DIR="E:\DjangoAdmin_Django_EleVue\public\uploads"
DJANGO_FILE_URL='http://file.django.elevue'温馨提示
- 确保
public/uploads/目录存在且有写入权限。 - 如需上传更大文件，可在
application/settings.py中调整FILE_UPLOAD_MAX_MEMORY_SIZE和DATA_UPLOAD_MAX_MEMORY_SIZE配置。
快速自检清单
遇到问题时，按以下清单逐项检查：
| 检查项 | 命令 | 期望结果 |
|---|---|---|
| Python 版本 | python --version | 3.12+ |
| pip 依赖 | pip list | grep django | Django 6.0+ |
| MySQL 服务 | mysql -uroot -p -e "SELECT 1" | 返回 1 |
| Redis 服务 | redis-cli -h 127.0.0.1 -p 6379 -a 123456 ping | PONG |
| .env 文件 | 确认 DATABASE_PASSWORD 和 REDIS_PASSWORD 正确 | 非空值 |
| 后端服务 | curl http://127.0.0.1:8000/login/captcha | 返回 JSON |
| Node.js 版本 | node -v | v18+ |
| pnpm 版本 | pnpm -v | 12.x+ |
| 前端服务 | 浏览器访问 http://localhost:8001 | 显示登录页 |
温馨提示
如果以上检查项均正常但仍无法运行，建议查看完整错误日志：
bash
# 后端日志
python manage.py runserver 2>&1 | tee backend.log
# 前端日志
cd ui && pnpm dev 2>&1 | tee frontend.log总结
本章节整理了项目开发中最常见的 10 个问题及其解决方案，涵盖环境配置、服务连接、依赖安装、权限控制和文件上传等方面。遇到问题时，建议先查看终端日志和浏览器控制台的错误信息，结合本章节的排查步骤逐一排除。如果问题仍未解决，可以查阅项目源码或联系开发团队获取支持。