雪碧图还在手写 background-position？试试这款 Vite + Vue3 构建期雪碧图插件
做活动页、游戏风 H5、后台图标墙时，**雪碧图（精灵图）**仍然很常见：多张 UI 小图合成一张，既省请求，整图也方便长期缓存。但痛点也很实在：
- 每帧
background-position/background-size要么手写一堆魔法数字，要么运行时拿 Canvas 量，难维护、难协作。 - 美术改一版切图，前端要跟着改 CSS，容易对不齐。
- 规则排布和「透明底不规则摆图」往往是两套做法，工具链不统一。
最近我把自用思路整理成了开源小工具 hyp-sprites-img：面向 Vite 5/6 + Vue 3，在构建期根据整图尺寸和你的布局规则，生成静态的每帧 x / y / width / height，运行时通过一个 Vue 组件用 background-position / background-size 展示指定帧。页面里按名字取图，不必在业务代码里推导坐标。
它能帮你省什么心
- 坐标在打包时就算好：结果写进 manifest（虚拟模块），运行时零推导，行为可预期。
- 声明式用法：
<hypSpritesImgCom>用name（哪张雪碧图组）和spritesName（哪一帧）切换，换图主要改配置和资源。 - 布局方式齐：横/竖等分、网格（先行后列），以及基于透明背景的连通域检测，规则图和不规则图都能覆盖常见需求。
- 开发体验：可选开启本地雪碧图预览页（仅
vite dev），按组看整图与每帧缩略图，一键复制组件片段或帧名数组，联调更省事。 - 和生态对齐：Vite 插件注入虚拟模块，
hyp-sprites-img/virtual可做 TypeScript 提示；组件从hyp-sprites-img/vue引入，避免 Node 侧去解析virtual:。
安装与最小配置
npm install hyp-sprites-img
对等依赖：vite（5 或 6）、vue（3）。在 vite.config.ts 里与 @vitejs/plugin-vue 一起使用：
import path from 'node:path'
import { defineConfig, type PluginOption } from 'vite'
import vue from '@vitejs/plugin-vue'
import { hypSpritesImg } from 'hyp-sprites-img'
export default defineConfig({
plugins: [
vue(),
hypSpritesImg(
[
{
url: path.resolve(__dirname, 'src/assets/sprites.png'),
name: 'sprites1',
spritesName: ['button', 'custom'],
},
],
) as PluginOption,
],
})
页面里：
<script setup lang="ts">
import { hypSpritesImgCom } from 'hyp-sprites-img/vue'
</script>
<template>
<hypSpritesImgCom name="sprites1" spritesName="button" width="100px" height="100px" />
</template>
TypeScript 项目在 env.d.ts 或 vite-env.d.ts 里加一行：
/// <reference types="hyp-sprites-img/virtual" />
需要本地预览时，给插件第二个参数 { preview: true }，终端会打印预览地址（具体路径以终端输出为准）。
设计上的一个小细节
主包 hyp-sprites-img 只导出 Vite 插件和布局工具，这样在 vite.config.ts 里 import { hypSpritesImg } from 'hyp-sprites-img' 时，Node 不会去碰 virtual:hyp-sprites-img。Vue 组件依赖虚拟模块，所以务必从 hyp-sprites-img/vue 导入组件——这是有意拆分，不是多余路径。
开发预览页一览
开启 preview 后，可在浏览器里按组浏览整图、核对每帧裁切，并临时改帧名（仅内存，不落盘）、复制组件片段或帧名列表，和设计与联调对齐更快。
适用边界（诚实说清楚）
- 等分模式：按
layout或默认比例推断切矩形，适合规整排布。 detect: true连通域模式：适合小图之间有透明分隔的雪碧图；若整块不透明或图形像素连在一起，会并成一个大区域，需要改图或改回等分。- 构建期只解析本地可解析的
url（例如path.resolve指向的工程内资源）。
结语
如果你在 Vue3 + Vite 项目里用雪碧图，又不想把精力耗在维护一坨 background-position 上，欢迎试试 hyp-sprites-img。开源协议 MIT。
若觉得有用，欢迎在 npm 留个使用记录、在 GitHub 点个 Star，或在 issue 里提需求与反馈。
