postcss-sprites 可自动合并雪碧图，需将图标统一放至 spritePath 指定目录、带单位写 background-position、Vite 中路径须相对于根目录且手动监听输出目录，否则 HMR 失效或定位不准。
用 postcss-sprites 在构建流程里自动合并图片
雪碧图不是手动拖进 PS 拼的，而是靠工具在打包时从 CSS 里识别 background-image 路径，批量合并、生成新图并重写样式。主流方案是 postcss-sprites，它能无缝接入 Webpack/Vite 的 PostCSS 流程。
常见错误现象：background-image: url(./icon-home.png) 写对了，但最终没合并——大概率是路径没被插件捕获，或文件不在 spritePath 指定目录下。
- 必须把所有要雪碧化的图标放在同一级目录（比如
src/assets/sprites/），插件只扫描这个路径下的 PNG/SVG - 在 PostCSS 配置中显式声明
spritePath，不能依赖默认值；Vite 用户注意：需通过postcss.config.js配置，vite.config.js里的css.postcss不会透传给该插件 - 图标尺寸最好统一（如都是 24×24），否则生成的雪碧图留白多、定位难，插件不会自动缩放或居中
background-position 值被重写后不准？检查单位和坐标系
插件生成的新 CSS 会把原 url() 替成雪碧图地址，并加上 background-position。不准的根源通常是单位混用或坐标原点理解偏差。
使用场景：你写了 background-position: -10px -20px，但实际图标偏移错位。
立即学习“前端免费学习笔记（深入）”；
- 确保原始 CSS 中所有
background-position值都带单位（px、rem等），不写单位（如-10 -20）会导致插件解析失败，回退为默认居左上 -
postcss-sprites默认以雪碧图左上角为原点，x 向右为正、y 向下为正；但人眼习惯“往上挪”写负 y，所以 -20px 是向上移，这点和最终渲染一致，不用反着调 - 如果用了
retina模式（@2x 图），插件会按物理像素计算 position，但 CSS 里写的仍是逻辑像素，无需手动除以 2
Webpack 里用 webpack-spritesmith 的兼容性陷阱
这货不是 PostCSS 插件，而是 Webpack Loader + Plugin 组合，适合老项目或需要深度控制雪碧图布局的场景，但和现代构建链路容易打架。
常见错误现象：Webpack 5 报 ModuleParseError: Module parse failed: Unexpected character '' —— 实际是它生成的 JSON 文件被其他 loader（如 url-loader）误处理了。
- 必须在
module.rules中明确排除雪碧图输出目录（如/\.spritesmith\.json$/），防止被asset/inline或url-loader二次处理 -
spritesmith本身不支持 SVG 作为输入源（只认 PNG/JPG），想用 SVG 得先转成 PNG，或换用postcss-sprites（它支持 SVG 雪碧） - 生成的
map.json默认是 CommonJS 格式，ESM 项目里import会报错，得配resolve.extensions或改用require()
Vite 下 postcss-sprites 的热更新失效问题
改一个图标文件，页面没刷新、雪碧图也没更新——不是插件坏了，是 Vite 的模块依赖追踪没把雪碧图输出纳入 HMR 范围。
性能影响：每次改图都得全量 rebuild，开发体验断层。
- 在
postcss.config.js的spritePath配置里，路径必须是相对于项目根目录的，不能用./开头的相对路径，否则 Vite 找不到依赖关系 - 插件生成的雪碧图（如
dist/assets/sprite.abc123.png）默认不在 Vite 的 watch 列表里，需手动加server.watch配置，监听输出目录 - 更稳的做法：把图标目录设为
public/下的子目录（如public/sprites/），插件直接读取，避免构建阶段 IO 与 HMR 冲突
雪碧图自动化真正的复杂点不在合并逻辑，而在于构建工具如何感知“哪些文件变了→要不要重跑→重跑时怎么通知 CSS 和 HTML 更新”。路径、单位、模块系统、HMR 这四块，漏掉任何一环，都会卡在“看着配置全对，就是不动”。
