GitLab Pages 能托管图片但必须放在 public/ 目录下，CI 配置需声明 artifacts: paths: [public] 或手动复制图片到 public/，HTML 中用相对路径引用（如 img/logo.png），且路径大小写敏感、不可用绝对路径或 <base href>。
GitLab Pages 能不能直接托管图片供 HTML 引用
能，但必须放在 public/ 目录下，且路径要和 CI 构建后的实际输出结构一致。GitLab Pages 只服务 public/（或你配置的 artifacts 输出目录）下的文件，src/、assets/ 或根目录里的图片默认 404。
- CI 构建前手动把图片复制进
public/img/，再在 HTML 里写<img src="img/logo.png"> - 如果用构建工具（如 Hugo、Jekyll），确认其输出目标是
public/，而非dist/或_site/—— 否则 GitLab CI 找不到文件 - 别在
.gitlab-ci.yml里漏掉artifacts: paths声明，比如只写了artifacts: [index.html]，图片会被忽略
.gitlab-ci.yml 中怎么配才能让图片不丢
关键不是“部署 HTML”，而是“确保所有静态资源都进入 Pages 输出”。GitLab CI 不自动扫描引用，它只按你声明的 artifacts 或 public/ 目录打包。
- 最稳做法：统一用
public/为构建输出目录，CI 配置里写artifacts: paths: [public] - 如果项目本身不生成
public/（比如纯手写 HTML），就在before_script里手动创建并复制：mkdir -p public/img && cp img/*.png public/img/ - 路径区分大小写：Linux 环境下
IMG/和img/是两个目录，HTML 中写的src="img/cat.jpg"必须和文件系统实际路径完全一致
HTML 里图片路径写相对还是绝对
写相对路径，且以 public/ 为根。GitLab Pages 的域名结构是 https://<group>.gitlab.io/<project>/<path>，所以 index.html 在 public/index.html，它引用 public/img/icon.svg 就该写 img/icon.svg，不是 /img/icon.svg。
-
/img/icon.svg是从域名根开始找，会去请求https://xxx.gitlab.io/img/icon.svg，404 - 子目录页面（如
public/blog/post.html）引用同一张图，仍写../img/icon.svg，不要硬编码项目名 - 避免用
<base href>—— GitLab Pages 不支持动态 base，容易导致 JS/CSS 也错位
为什么本地能打开 HTML，上线就看不到图
因为本地双击打开是 file:// 协议，浏览器绕过同源策略，能读同目录下所有文件；GitLab Pages 是 HTTP 服务，路径解析严格遵循 HTML 当前 URL 和 public/ 结构。
立即学习“前端免费学习笔记（深入）”；
- 检查浏览器开发者工具的 Network 标签页，看图片请求返回的是 404 还是 403 —— 403 说明文件存在但权限/路径配置有误
- 运行
gitlab-runner exec docker test本地模拟 CI 环境，进容器后ls -R public/确认图片真在那儿 - GitLab Pages 默认不支持
.webp？不是，只要 MIME 类型没被显式禁用，它就按文件后缀自动设Content-Type；但旧浏览器可能不渲染，这不是部署问题
最容易被忽略的是：CI job 成功不代表 Pages 更新成功。点进 Settings > Pages 页面，确认 “Latest successful job” 下面显示的是你刚推送的 commit，而不是上周的缓存构建 —— 有时候 .gitlab-ci.yml 改了但没触发新 job，图片自然不会更新。
