Django ≥ 5.0 必须用 STORAGES 字典配置替代 DEFAULT_FILE_STORAGE，否则仍走本地；常见错误是版本不匹配导致配置失效。
直接配置 DEFAULT_FILE_STORAGE 就能实现 Django 文件直传 OSS，但多数人卡在 403、bucket not found、endpoint 错配这三类错误上——不是代码写错，而是配置项没对齐阿里云控制台的实际状态。
为什么 DEFAULT_FILE_STORAGE 配置后上传仍走本地？
最常见原因是 Django 5.0+ 引入了 STORAGES 字典配置，它会完全覆盖 DEFAULT_FILE_STORAGE。如果你用的是 Django ≥ 5.0，只设 DEFAULT_FILE_STORAGE 是无效的。
- 检查 Django 版本：
python -c "import django; print(django.VERSION)" - Django ≥ 5.0 必须用：
STORAGES = { "default": { "BACKEND": "aliyun_oss2_storage.backends.AliyunMediaStorage" }, "staticfiles": { "BACKEND": "aliyun_oss2_storage.backends.AliyunStaticStorage" } } - Django DEFAULT_FILE_STORAGE 和
STATICFILES_STORAGE - 运行
python manage.py shell后执行from django.core.files.storage import default_storage; print(default_storage.__class__)，输出类名必须含AliyunMediaStorage才算生效
END_POINT 和 BUCKET_NAME 怎么填才不报 403 或 bucket not found？
错误信息里其实已经告诉你答案了，只是很多人忽略。比如报错中出现 HostId: xxx.oss-cn-hangzhou.aliyuncs.com，说明你该用 oss-cn-hangzhou.aliyuncs.com，而不是随便抄个文档里的示例值。
-
END_POINT必须和 Bucket 所在区域严格一致，格式为oss-<region>.aliyuncs.com</region>，例如oss-cn-shanghai.aliyuncs.com -
BUCKET_NAME必须和阿里云 OSS 控制台「Bucket 列表」里显示的**完整名称**一模一样（区分大小写、不能带路径） - 如果控制台创建 Bucket 时选了「公共读」，但代码里设了
BUCKET_ACL_TYPE = "private"，上传成功但 URL 返回 403 —— 因为生成的签名 URL 默认按 private 权限签，而 public-read 的 bucket 不需要签名 - 临时调试可加
ALIYUN_OSS_CNAME = ""（空字符串），避免自定义域名解析或 HTTPS 配置干扰
上传后 URL 是签名链接还是公开链接？
取决于两个地方：Bucket 的 ACL 类型 + 是否启用了 ALIYUN_OSS_CNAME。它不是由代码“生成”出来的，而是由 OSS 服务端策略决定的。
立即学习“Python免费学习笔记（深入）”；
-
BUCKET_ACL_TYPE = "public-read"且未设ALIYUN_OSS_CNAME：URL 形如https://<bucket>.oss-<region>.aliyuncs.com/<key>，无需签名，直接可访问 -
BUCKET_ACL_TYPE = "private"：URL 默认带签名参数（?Expires=...&OSSAccessKeyId=...），过期即失效 - 设了
ALIYUN_OSS_CNAME = "cdn.example.com"且已正确 CNAME 解析到 OSS Endpoint：URL 变成https://cdn.example.com/<key>，但权限逻辑不变 —— public-read 才能裸访问，private 仍需签名 - 注意：
PREFIX_URL这个变量在部分旧版 fork 中存在，但django-aliyun-oss2-storage官方版不认它；强行加会导致 URL 拼接重复或 403
真正容易被忽略的点是：OSS 的 endpoint 区域、bucket 名称、ACL 类型这三项必须在控制台和 settings.py 里**三者完全对齐**，差一个字符或一个区域后缀都会导致静默失败或 403 —— 不要依赖“看起来差不多”，要用错误响应里的 HostId 或 Endpoint 字段反向确认。
