compass 雪碧图已不可用，因其依赖废弃的 ruby 版本和插件机制，且 dart sass 不支持文件系统访问；推荐改用 postcss + postcss-sprites 在构建流程中自动合成雪碧图。
Compass 已废弃，Sass 原生不支持雪碧图自动合成，强行用旧 Compass 方案会卡在 Ruby 环境、依赖冲突、无法构建。
Compass spriting 为什么现在跑不起来
Compass 的雪碧图功能依赖 Ruby 1.9–2.4 和老旧的 chunky_png、rb-fsevent 等原生扩展，而现代系统（macos Sonoma+、ubuntu 22.04+）默认 Ruby ≥ 3.0，compass gem 早已停止维护，bundle install 直接报 cannot load such file -- chunky_png 或 uninitialized constant Compass::Sprites。
- Node.js 环境下装
compass无意义——它根本不是 npm 包 - 即使降级 Ruby，新版 Sass（Dart Sass）已移除对 Compass 插件机制的支持，
@import "compass/utilities/sprites"会触发File to import not found - Compass 的
sprite-map()函数返回的是运行时生成的 CSS 字符串，和当前主流构建流程（Vite、webpack）完全脱节
替代方案：用 PostCSS + postcss-sprites 接入现有流程
比硬啃 Compass 更实际的做法，是让雪碧图合成发生在 CSS 编译后、打包前，由 PostCSS 插件处理 background-image: url("icon-*.png") 类声明，并自动合并、替换路径、注入尺寸。
- 安装：
npm install postcss-sprites --save-dev - 配置（以 PostCSS 配置为例）：
module.exports = { plugins: [ require('postcss-sprites')({ spritePath: 'dist/img/sprites', retina: true }) ] } - 源码中写
background-image: url("icon-home.png")，插件自动找同目录下所有icon-*.png合成一张图，生成icon-sa7f3d.png并改写 CSS 中的 URL 和background-position - 注意：必须确保图片路径在构建前已存在，且不能是 Webpack 的
require()或 Vite 的new URL()动态导入形式
Dart Sass 里用 @use 写雪碧图？不行，别试了
有人想用 Sass 的自定义函数 + 文件系统 API 模拟 Compass 行为，但 Dart Sass 是纯编译器，@use "sass:meta" 或 @use "sass:math" 都不提供读取磁盘、遍历文件夹的能力，@function sprite-url($name) { @return url("...") } 只能返回静态路径，无法真正合成。
立即学习“前端免费学习笔记（深入）”；
-
node-sass虽然支持includePaths和自定义函数，但它也已归档，且同样无法安全访问文件系统（尤其在 windows WSL 或 CI 环境） - 试图用
fs.readdirSync在自定义函数里读图，会触发SassError: Function cannot be called outside of a module或直接崩溃 - 真要 Sass 层控制，唯一可行的是把雪碧图元数据（位置、尺寸）提前生成 json，再用
@use "sass:json"导入——但这等于手动维护，失去了“自动”的意义
雪碧图自动合成的关键不在 Sass 本身，而在构建链路中哪一环能可靠读图、写图、改 CSS。Compass 把这件事绑死在 Ruby 生态里，而今天最稳的落点，其实是 PostCSS 插件或 Webpack 的 svg-sprite-loader（针对 SVG）。别在 Sass 里找答案，它早就没这个权限了。