本文详解 django 项目中 bootstrap 轮播图（carousel）无法显示本地图片的常见原因，重点说明静态文件路径配置规范、`src` 属性书写规则及调试方法，帮助开发者快速定位并解决“图片加载失败但线上 url 正常”的问题。
在 Django 项目中使用 Bootstrap 轮播图时，若 <img src="cartoon.jpg"> 无法显示本地图片，而换成 https://example.com/cartoon.jpg 却能正常加载，这通常不是 HTML 或 Bootstrap 语法错误，而是静态资源路径解析机制未被正确遵循所致。
Django 默认不会将任意相对路径（如 "cartoon.jpg"）自动映射到静态文件目录。浏览器会将该路径解释为相对于当前 URL 的路径。例如，当访问 /blog/home/ 时，src="cartoon.jpg" 实际请求的是 /blog/home/cartoon.jpg，而非你期望的根目录下的图片。
✅ 正确做法是：所有本地静态图片路径必须以 / 开头（即绝对路径），且图片需置于 Django 静态文件系统可服务的目录中。
✅ 正确路径写法（推荐）
<img src="/static/images/cartoon.jpg" class="d-block w-100" alt="Cartoon character">
或（若已配置 STATIC_URL = '/static/' 且图片直接放在 static/ 根目录）：
<img src="/static/cartoon.jpg" class="d-block w-100" alt="Cartoon character">
⚠️ 注意：仅写 src="/cartoon.jpg" 是不推荐且易出错的——它要求图片直接部署在 Web 服务器根目录（如 Nginx/Apache 的 document_root），绕过了 Django 的静态文件管理机制，在开发环境（DEBUG=True）下甚至可能根本不可用。
? Django 静态文件标准配置（确保生效）
- 在 settings.py 中确认已配置：
STATIC_URL = '/static/' STATICFILES_DIRS = [BASE_DIR / 'static'] # 开发时查找静态文件的目录 # 生产环境还需配置 STATIC_ROOT（用于 collectstatic）
- 图片应存放于项目根目录下的 static/ 文件夹中（如 myproject/static/cartoon.jpg 或更规范的 myproject/static/images/rick_morty.jpg）。
- 模板中必须使用 {% load static %} + {% static 'images/rick_morty.jpg' %}（最佳实践）：
{% load static %} ... <img src="{% static 'images/rick_morty.jpg' %}" class="d-block w-100" alt="Rick and Morty">
? 快速排查步骤
- 打开浏览器开发者工具（F12）→ Network 标签页 → 刷新页面 → 查看图片请求是否返回 404；
- 点击该 404 请求，观察 Preview/Response 是否提示 “Page not found” 或路径明显错误；
- 在终端执行 python manage.py findstatic cartoon.jpg，验证 Django 是否能定位该文件；
- 检查 static/ 目录是否在 STATICFILES_DIRS 中，且无拼写/大小写错误（Linux/macOS 对文件名大小写敏感）。
✅ 修改后完整示例（推荐写法）
{% extends 'base.html' %}
{% load static %}
{% block title %}轮播图示例{% endblock %}
{% block body %}
<div class="container">
<div id="carouselExampleCaptions" class="carousel slide">
<div class="carousel-inner">
<div class="carousel-item active">
<img src="{% static 'images/cartoon.jpg' %}" class="d-block w-100" alt="卡通角色">
<div class="carousel-caption d-none d-md-block">
<h5>第一张幻灯片</h5>
<p>占位内容</p>
</div>
</div>
<div class="carousel-item">
<img src="{% static 'images/rick_morty.jpg' %}" class="d-block w-100" alt="瑞克和莫蒂">
<div class="carousel-caption d-none d-md-block">
<h5>第二张幻灯片</h5>
<p>占位内容</p>
</div>
</div>
</div>
<!-- 控制按钮等保持不变 -->
</div>
</div>
{% endblock %}? 总结：永远不要依赖裸相对路径（如 "cartoon.jpg"）或根相对路径（如 "/cartoon.jpg"）加载静态资源；务必通过 {% static %} 模板标签生成路径——它既兼容开发与生产环境，又支持版本哈希、CDN 集成等高级特性，是 Django 官方唯一推荐的静态文件引用方式。
