Whitebox Packages：HTML文件嵌入图片在最终构建中不显示问题咨询

阿华AIGC实验室

2026-5-7

解决HTML文件嵌入图片构建后不显示的问题

Hey Greg, 别慌，在HTML文件（比如intro、readme这类）里嵌入图片后构建产物不显示的问题很常见，这个功能本身是完全支持的，大概率是路径配置或者构建工具处理逻辑的问题。下面是你需要逐一排查的关键点：

检查图片引用路径的正确性
这是最常见的原因：
- 优先使用相对路径，路径基准是当前HTML文件的位置。举个项目结构的例子：
```
你的项目/
├── static/
│   └── banner.png
├── intro.html
└── docs/
    └── readme.html
```
  那intro.html里的图片标签应该写 <img src="./static/banner.png" alt="Banner">；而docs/readme.html里要写成 <img src="../static/banner.png" alt="Banner">。
- 注意路径的大小写，很多构建环境（比如基于Linux的服务器）对文件名大小写敏感，Banner.png和banner.png会被判定为不同文件。
确认构建工具的资源配置
如果你用Webpack、Vite、Parcel这类构建工具，要确保图片被正确纳入构建流程：
- 大部分工具默认会处理public目录下的静态资源，或者通过import语法引入的图片。如果你的图片放在自定义目录，可能需要在工具配置文件里添加资源解析规则。
- 有些工具会给图片重命名（比如加上哈希值）来做缓存优化，这时候直接写固定文件名的路径会失效。可以用模块导入的方式动态设置路径，比如：
```
<script type="module">
  import banner from '../static/banner.png';
  document.getElementById('page-banner').src = banner;
</script>
<img id="page-banner" alt="页面横幅">
```
验证构建产物中的图片是否存在
构建完成后，去你的输出目录（通常是dist或者build）里检查：
- 看看图片有没有被打包进去，如果找不到图片文件，说明构建工具没识别到这个资源，需要调整路径写法或者工具配置。
- 如果图片存在，但路径和你HTML里写的不一致，就要修改HTML中的引用路径来匹配产物里的实际路径。
排查HTML文件的位置变更
部分构建工具会对HTML文件做目录整理（比如把所有HTML文件放到pages子目录），这时候原来的相对路径就会失效。比如构建后intro.html被移到dist/pages/intro.html，那原来的./static/banner.png就要改成../static/banner.png。