如何让Vite解析React组件库Sass文件url()中的资源？

问题根源 #

你遇到的问题是因为Vite默认对node_modules里的包做预构建，且默认认为这些包是已经编译完成的产物。而你的包是源码形式（TypeScript、未编译的Sass），Sass里的url()相对路径是基于包自身的目录结构，消费端Vite不会自动处理这种跨包的资源引用，导致浏览器把图片路径解析成了消费端项目根目录下的http://localhost:8080/assets/images/bg.png，自然返回404。

下面给你几个可行的解决方案：

方案1：配置消费端Vite，让它正确处理你的包 #

在消费端项目的vite.config.js里添加以下配置，告诉Vite你的包需要被当作源码处理，并且允许访问包内的资源：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  // 让Vite预构建你的包，处理其中的TS和Sass
  optimizeDeps: {
    include: ['my-package'],
  },
  // 允许Vite读取node_modules中你的包的文件
  server: {
    fs: {
      allow: ['node_modules/my-package'],
    },
  },
})

同时，确保你的包的package.json里配置了正确的源码入口：

{
  "name": "my-package",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts"
}

方案2：在包内修改资源引用方式（推荐开发调试用） #

把图片通过ES模块导入到组件中，让Vite自动处理资源路径，避免相对路径的混乱：

1. 修改my-component.tsx，导入图片并通过CSS变量传递路径：

import React from 'react'
import '../scss/my-component.scss'
// 直接导入图片资源
import bgImage from '../../assets/images/bg.png'

export const MyComponent = () => {
  return (
    // 用CSS变量传递图片路径
    <div 
      className="custom-bg" 
      style={{ '--bg-image': `url(${bgImage})` } as React.CSSProperties}
    ></div>
  )
}

2. 对应的Sass文件修改为使用CSS变量：

.custom-bg {
  background-image: var(--bg-image);
}

这种方式下，Vite会自动把图片打包到消费端项目的dist/assets目录，并生成正确的访问路径，彻底解决404问题。

方案3：提前构建你的包（推荐正式发布用） #

如果你的包要发布到npm，最好提前用Vite或Rollup构建成产物，确保资源路径在构建时就被正确处理：

1. 给你的包添加vite.config.js：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: path.resolve(__dirname, 'src/index.ts'),
      name: 'MyPackage',
      formats: ['es', 'umd'],
      fileName: (format) => `my-package.${format}.js`,
    },
    rollupOptions: {
      // 排除React相关依赖，让消费端提供
      external: ['react', 'react-dom'],
      output: {
        globals: {
          react: 'React',
          reactDOM: 'ReactDOM',
        },
      },
    },
    // 指定打包后的资源目录
    assetsDir: 'assets',
  },
})

2. 执行vite build构建包后，修改包的package.json指向构建产物：

{
  "name": "my-package",
  "type": "module",
  "main": "./dist/my-package.umd.js",
  "module": "./dist/my-package.es.js",
  "types": "./dist/index.d.ts",
  "files": ["dist"]
}

这样消费端安装包后，直接使用的是已经处理好资源路径的产物，不会再出现404问题。

内容的提问来源于stack exchange，提问作者Coldiary