雪碧图还在手写 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:。

安装与最小配置

bash 复制代码

npm install hyp-sprites-img

对等依赖：vite（5 或 6）、vue（3）。在 vite.config.ts 里与 @vitejs/plugin-vue 一起使用：

ts 复制代码

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,
  ],
})

页面里：

vue 复制代码

<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 里加一行：

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 导入组件 ------ 这是有意拆分，不是多余路径。

支持图片预览，配置帧名称，及复制配置信息

适用边界（诚实说清楚）

等分模式 ：按 layout 或默认比例推断切矩形，适合规整排布。
detect: true 连通域模式 ：适合小图之间有透明分隔的雪碧图；若整块不透明或图形像素连在一起，会合成一个大区域，需要改图或改回等分。
构建期只解析本地可解析 的 url。

结语

如果你也在 Vue3 + Vite 项目里用雪碧图，又不想把生命浪费在维护一坨 background-position 上，欢迎试试 hyp-sprites-img 。开源协议 MIT。

npm：www.npmjs.com/package/hyp...
GitHub：github.com/Rupiong

若觉得有用，欢迎在 npm 留个使用记录、在 GitHub 点个 Star，或在 issue 里吐槽需求。