Rollup打包React组件库：仅MasterCard图标显示其余图片缺失问题

问题概述 #

开发React组件库时使用Rollup打包，4张图片在Storybook中加载正常，但将库安装到其他React应用后，仅mastercardLogo.png能显示，其余visaLogo.png、cardBackgroundVisa.png、cardBackgroundMasterCard.png均缺失。

代码片段 #

CreditCardForm.tsx #

import React, { useState } from "react";
import "./CreditCardForm.css";
import mastercardLogo from "../../../images/mastercardLogo.png";
import visaLogo from "../../../images/visaLogo.png";
import cardBackgroundMasterCard from "../../../images/cardBackgroundMasterCard.png";
import cardBackgroundVisa from "../../../images/cardBackgroundVisa.png";

interface CreditCardFormProps {
  name: string;
  onChangeName: () => void;
  cardNumber: string;
  onChangeCardNumber: () => void;
  expirationDate: string;
  onChangeExpirationDate: () => void;
  cvv: string;
  onChangeCvv: () => void;
  cardType: string;
  onChangeCardType: () => void;
  onSubmit: () => void;
}

const CreditCardForm = (props: CreditCardFormProps) => {
  const [cardType, setCardType] = useState("mastercard");

  const onChangeCardType = (e: React.ChangeEvent<HTMLInputElement>) => {
    setCardType(e.target.value);
  };

  return (
    <>
      <div
        className="card-container"
        style={{
          backgroundImage: `${
            cardType === "visa"
              ? `url(${cardBackgroundVisa})`
              : `url(${cardBackgroundMasterCard})`
          }`,
        }}
      >
        <div className="card-type">
          <img
            src={cardType === "visa" ? visaLogo : mastercardLogo}
            alt="logo"
            className="logo-style"
          />
        </div>

        <div className="card-number">
          <p>4829 0921 8391 4458</p>
        </div>

        <div className="card-info">
          <div className="card-name">
            <p className="title">Cardholder name</p>
            <p className="info">John Doe</p>
          </div>

          <div className="card-expiration">
            <p className="title">Valid Thru</p>
            <p className="info">01/26</p>
          </div>
        </div>
      </div>

      {/* 表单输入部分省略 */}
    </>
  );
};

export default CreditCardForm;

原rollup.config.js #

import resolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import typescript from "@rollup/plugin-typescript";
import dts from "rollup-plugin-dts";
import packageJson from "./package.json" assert { type: "json" }; 
import external from "rollup-plugin-peer-deps-external";
import postcss from "rollup-plugin-postcss";
import url from 'rollup-plugin-url';
import image from "@rollup/plugin-image";


export default [

  {
    input: "src/index.ts", 
    output: [
      {
        file: packageJson.main,
        format: "cjs",
        sourcemap: true,
      }, 
      {
        file: packageJson.module,
        format: "esm",
        sourcemap: true,
      }, 
    ],
    plugins: [
      resolve(),
      commonjs(),
      typescript({ tsconfig: "./tsconfig.json" }),
      external(),
      postcss(), 
      url(),
      image(),
    ], 
  },

  
  {
    input: "dist/esm/types/index.d.ts",
    output: [
      { file: "dist/index.d.ts", format: "esm", globals: { react: "React" } },
    ],
    plugins: [dts()],
    external: ["react", "react-dom",/\.css$/ ],
  },
];

问题原因 #

1. 插件冲突：同时使用rollup-plugin-url和@rollup/plugin-image两个图片处理插件，二者功能重叠，导致部分图片的处理逻辑异常，仅部分图片被正确打包。
2. 文件名大小写敏感：部分文件名存在大小写差异（如cardBackgroundMasterCard.png中的MasterCard），Windows环境（Storybook运行环境）不区分大小写，但Linux/macOS环境（目标应用运行环境）会因大小写不匹配导致图片加载失败。
3. 资源输出路径配置缺失：未明确配置图片的输出目录和引用路径，导致打包后图片未被放置到正确位置，目标应用无法找到资源。

解决步骤 #

步骤1：移除冲突插件，保留一个图片处理插件 #

选择其中一个插件即可，推荐使用rollup-plugin-url（可灵活配置输出路径），移除@rollup/plugin-image。修改后的rollup.config.js插件配置如下：

plugins: [
  resolve(),
  commonjs(),
  typescript({ tsconfig: "./tsconfig.json" }),
  external(),
  postcss(), 
  url({
    destDir: 'dist/images', // 指定图片输出目录
    publicPath: '/images/', // 图片引用的公共路径
    include: ['**/*.png'], // 仅处理png格式图片
    limit: 0 // 不将图片转为base64，全部输出为文件
  })
],

若倾向于将小图片转为base64嵌入代码，可保留@rollup/plugin-image并移除rollup-plugin-url，该插件会自动将图片转为base64字符串，无需额外配置。

步骤2：统一文件名与代码引用的大小写 #

检查所有图片文件名和代码中的导入语句，确保大小写完全一致。例如：

• 若文件名为cardBackgroundMastercard.png（小写c），则代码中导入需改为import cardBackgroundMastercard from "../../../images/cardBackgroundMastercard.png"。
• 确保操作系统（尤其是目标应用运行环境）的文件系统大小写敏感配置一致。

步骤3：验证打包结果 #

执行打包命令后，查看dist/images目录是否包含所有4张图片。然后将库安装到目标应用，打开浏览器开发者工具的网络面板，检查缺失图片的请求路径是否正确，若返回404则需调整publicPath配置（例如目标应用部署在子路径时，publicPath需改为/your-app-path/images/）。

步骤4：确保package.json正确配置 #

检查package.json中的files字段，确保dist/images目录被包含在发布包中：

"files": [
  "dist",
  "dist/images"
]

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