unplugin-images

自动扫描你的图片目录，生成可直接导入使用的常量映射文件（默认 src/assets/r.ts）。基于 unplugin，兼容 Vite、Rollup、Webpack、Rspack、esbuild、Farm、Nuxt、Astro 等生态。

特性

• 自动递归扫描图片目录（默认 src/assets/images）
• 按规则生成常量名，避免手写路径与拼写错误
• 构建开始自动生成；开发环境可监听变更并自动再生成
• 生成文件内容不变则跳过写入，避免不必要的重建
• 在构建开始时生成图片常量文件，开发模式自动监听与增量生成；在构建结束时释放 watcher。

安装

# 推荐 pnpm
pnpm add -D unplugin-images
# 或
npm i -D unplugin-images
# 或
yarn add -D unplugin-images

快速开始（Vite）

// vite.config.ts
import Images from 'unplugin-images/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Images({
      // 可选：图片目录与输出文件（默认见下方“配置项”）
      // dir: 'src/assets/images',
      // dts: 'src/assets/r.ts',
    }),
  ],
})

在代码中使用（假设使用默认输出路径）：

// 示例：在任意组件/模块中
import { R } from '@/assets/r' // 或根据你的路径别名/相对路径导入

// R.ICON_LOGO_PNG、R.BANNER_AT_2X_WEBP 等即为具体图片资源

生成文件（默认 src/assets/r.ts）的典型结构：

import ICON_LOGO_PNG from './images/icons/logo.png'
// ...

const R = {
  ICON_LOGO_PNG,
  // ...
}

export { R }

常量命名规则

• 使用「目录名文件名后缀」的全大写下划线风格，例如：
  • icons/logo.png → ICONS_LOGO_PNG
  • 根目录文件 [email protected] → BANNER_AT_2X_WEBP
• 目录分隔符转换为下划线；- 转为 _；@ 转为 _AT_
• 后缀会追加为大写（如 _PNG、_SVG）

配置项 Options

interface Options {
  /** 图片目录（相对项目根目录或绝对路径） */
  dir?: string // 默认：'src/assets/images'
  /** 生成的常量文件路径（相对项目根目录或绝对路径） */
  dts?: string // 默认：'src/assets/r.ts'
  /** 是否在开发时监听变更自动再生成（默认：开发 true，生产 false） */
  watch?: boolean
  /** 项目根目录，用于解析相对路径（默认：process.cwd()） */
  root?: string
}

不同构建器的用法

// rollup.config.ts
import Images from 'unplugin-images/rollup'

export default {
  plugins: [
    Images({
      /* options */
    }),
  ],
}

// webpack.config.js
module.exports = {
  // ...
  plugins: [
    require('unplugin-images/webpack')({
      /* options */
    }),
  ],
}

// rspack.config.ts
import Images from 'unplugin-images/rspack'

export default {
  plugins: [
    Images({
      /* options */
    }),
  ],
}

// esbuild.config.ts
import { build } from 'esbuild'
import Images from 'unplugin-images/esbuild'

build({
  plugins: [Images()],
})

// farm.config.ts
import Images from 'unplugin-images/farm'

export default {
  plugins: [
    Images({
      /* options */
    }),
  ],
}

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    [
      'unplugin-images/nuxt',
      {
        /* options */
      },
    ],
  ],
})

// astro.config.mjs
import images from 'unplugin-images/astro'

export default {
  integrations: [
    images({
      /* options */
    }),
  ],
}

工作机制

• 构建开始时会生成一次常量文件
• 当 watch: true（默认开发环境）时，监听图片文件与目录的新增/修改/删除并自动再生成
• 若输出内容与上次完全一致，将跳过写入

许可协议

MIT