file-loader vs image-webpack-loader vs raw-loader vs url-loader
Webpack 静态资源加载器选型指南
搜索包...
file-loaderimage-webpack-loaderraw-loaderurl-loader类似的npm包:

Webpack 静态资源加载器选型指南

file-loader、image-webpack-loader、raw-loader 和 url-loader 都是 Webpack 生态中用于处理静态资源的加载器（loader）。file-loader 将文件输出为独立资源并返回其路径；url-loader 在文件较小时将其转为 Base64 内联，较大时回退到 file-loader；raw-loader 以字符串形式导入文件内容；image-webpack-loader 则专注于对图像进行压缩优化。需要注意的是，随着 Webpack 5 引入 Asset Modules，前三个 loader 已被官方标记为废弃，推荐使用原生配置替代，而 image-webpack-loader 因其专用优化功能仍具实用价值。

npm下载趋势

3 年

GitHub Stars 排名

统计详情

npm包名称
下载量
Stars
大小
Issues
发布时间
License
file-loader01,844-16 年前MIT
image-webpack-loader02,0143.56 MB81-MIT
raw-loader0843-56 年前MIT
url-loader01,395-46 年前MIT

Webpack 资源加载器深度对比：file-loader、image-webpack-loader、raw-loader 与 url-loader

在基于 Webpack 的前端工程体系中，如何高效处理静态资源（如图片、字体、文本等）是构建性能和用户体验的关键环节。file-loader、image-webpack-loader、raw-loader 和 url-loader 都是 Webpack 生态中用于处理不同资源类型的经典加载器（loader）。然而，随着 Webpack 5 内置 Asset Modules 的推出，这些包的定位和适用性发生了显著变化。本文将从实际工程角度出发，深入剖析它们的技术差异、使用场景及迁移建议。

⚠️ 重要前提：Webpack 5 的内置替代方案

首先必须明确：file-loader、raw-loader 和 url-loader 均已在官方文档中标记为“不再推荐用于 Webpack 5”。Webpack 5 引入了 Asset Modules，通过 type: 'asset/resource'、type: 'asset/inline' 和 type: 'asset/source' 等原生配置，完全覆盖了这三个 loader 的核心功能，且无需额外安装依赖。因此，在新项目中应优先使用 Asset Modules。

image-webpack-loader 则不同——它专注于图像压缩优化，不涉及资源输出方式，因此仍具有独立价值，常与 Asset Modules 或其他 loader 配合使用。

下面我们将逐一分析各包的功能、适用边界及代码示例。

📁 file-loader：将文件输出为独立资源

file-loader 的作用是将匹配的文件复制到输出目录，并返回其公共路径（public path）。这适用于需要保留原始文件格式、避免 Base64 编码的大文件（如大图、字体、PDF 等）。

// webpack.config.js (Webpack 4)
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: ['file-loader']
      }
    ]
  }
};

// 在 JS 中引用
import imgUrl from './image.png';
// imgUrl 为类似 '/static/media/image.abc123.png' 的字符串

但在 Webpack 5 中，应改用：

// webpack.config.js (Webpack 5)
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        type: 'asset/resource' // 等效于 file-loader
      }
    ]
  }
};

注意：file-loader 已被官方标记为 deprecated，不应在新项目中使用。

🖼️ image-webpack-loader：专用于图像压缩优化

image-webpack-loader 并不改变资源的输出方式，而是对图像进行无损或有损压缩（支持 PNG、JPEG、GIF、SVG 等），以减小最终 bundle 体积。它通常与其他 loader（如 file-loader 或 Asset Modules）串联使用。

// webpack.config.js (Webpack 4)
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif|svg)$/i,
        use: [
          'file-loader',
          {
            loader: 'image-webpack-loader',
            options: {
              mozjpeg: { progressive: true, quality: 65 },
              optipng: { enabled: false },
              pngquant: { quality: [0.65, 0.8], speed: 4 }
            }
          }
        ]
      }
    ]
  }
};

在 Webpack 5 中，可与 Asset Modules 组合：

// webpack.config.js (Webpack 5)
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif|svg)$/i,
        type: 'asset/resource',
        use: [
          {
            loader: 'image-webpack-loader',
            options: { /* 同上 */ }
          }
        ]
      }
    ]
  }
};

关键点：image-webpack-loader 未被废弃，仍是图像优化的有效工具，尤其适合对 Lighthouse 性能评分有要求的项目。

📜 raw-loader：以字符串形式内联文件内容

raw-loader 将文件内容作为 UTF-8 字符串导入，常用于读取文本文件（如 .txt、.md、.glsl 着色器代码等）。

// webpack.config.js (Webpack 4)
module.exports = {
  module: {
    rules: [
      {
        test: /\.txt$/,
        use: 'raw-loader'
      }
    ]
  }
};

// 在 JS 中引用
import text from './content.txt';
// text 为文件的完整字符串内容

Webpack 5 中的等效写法：

// webpack.config.js (Webpack 5)
module.exports = {
  module: {
    rules: [
      {
        test: /\.txt$/,
        type: 'asset/source' // 等效于 raw-loader
      }
    ]
  }
};

注意：raw-loader 已被官方标记为 deprecated，不应在新项目中使用。

🔗 url-loader：小文件转 Base64，大文件回退到 file-loader

url-loader 的核心逻辑是：当文件小于指定 limit 时，将其转为 Data URL（Base64）内联；否则委托给 file-loader 处理。这可减少 HTTP 请求，但会增大 JS bundle 体积。

// webpack.config.js (Webpack 4)
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        use: [
          {
            loader: 'url-loader',
            options: {
              limit: 8192 // 8KB
            }
          }
        ]
      }
    ]
  }
};

// 若 image.png < 8KB，则 import 返回 'data:image/png;base64,...'
// 否则行为同 file-loader

Webpack 5 使用 Asset Modules 实现相同逻辑：

// webpack.config.js (Webpack 5)
module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        type: 'asset', // 自动选择 inline 或 resource
        parser: {
          dataUrlCondition: {
            maxSize: 8 * 1024 // 8KB
          }
        }
      }
    ]
  }
};

注意：url-loader 已被官方标记为 deprecated，不应在新项目中使用。

🔄 迁移建议：从旧 loader 到 Webpack 5 Asset Modules

旧方案Webpack 5 替代方案
file-loadertype: 'asset/resource'
raw-loadertype: 'asset/source'
url-loader（无 fallback）type: 'asset/inline'
url-loader（带 limit）type: 'asset' + parser.dataUrlCondition.maxSize

例外：image-webpack-loader 无需替换，可继续与 Asset Modules 配合使用。

💡 实际工程决策指南

场景 1：处理用户上传的头像（小图，需快速加载）

  • ✅ 推荐：type: 'asset' + maxSize: 10240（10KB）
  • 理由：小图内联可减少请求，提升首屏速度。

场景 2：加载产品详情页的高清主图（>100KB）

  • ✅ 推荐：type: 'asset/resource' + image-webpack-loader
  • 理由：避免污染 JS bundle，同时通过压缩减小传输体积。

场景 3：在 WebGL 应用中加载 GLSL 着色器代码

  • ✅ 推荐：type: 'asset/source'
  • 理由：直接获取字符串内容，便于注入 Shader 程序。

场景 4：遗留 Webpack 4 项目升级

  • ✅ 步骤：
    1. 移除 file-loader / raw-loader / url-loader 依赖
    2. 将 loader 配置替换为对应的 Asset Module 配置
    3. 保留 image-webpack-loader（如有图像优化需求）

📌 总结

包名功能是否废弃Webpack 5 替代方案
file-loader输出独立文件✅ 是type: 'asset/resource'
image-webpack-loader图像压缩优化❌ 否无需替换，配合 Asset Modules 使用
raw-loader以字符串导入文件✅ 是type: 'asset/source'
url-loader小文件 Base64 内联✅ 是type: 'asset' + dataUrlCondition

核心结论：除 image-webpack-loader 外，其余三个 loader 均已被 Webpack 5 原生能力取代。新项目应直接使用 Asset Modules，旧项目应制定迁移计划。image-webpack-loader 作为专注图像优化的工具，在需要精细控制压缩参数的场景下仍有不可替代的价值。

如何选择: file-loader vs image-webpack-loader vs raw-loader vs url-loader

  • file-loader:

    不要在新项目中使用 file-loader —— 它已被 Webpack 5 的 type: 'asset/resource' 完全取代。如果你仍在维护 Webpack 4 项目且需要将文件输出为独立资源（如大图、字体），可暂时使用它，但应尽快迁移到 Asset Modules。

  • image-webpack-loader:

    当你需要对 PNG、JPEG、GIF 或 SVG 等图像进行压缩优化（如降低文件体积以提升页面加载速度）时，选择 image-webpack-loader。它不处理资源输出方式，而是作为优化步骤与其他 loader 或 Webpack 5 Asset Modules 配合使用，适合对性能有严格要求的项目。

  • raw-loader:

    不要在新项目中使用 raw-loader —— 它已被 Webpack 5 的 type: 'asset/source' 取代。仅在 Webpack 4 遗留项目中用于以字符串形式导入文本类文件（如 .txt、.md 或着色器代码），新项目应直接使用原生配置。

  • url-loader:

    不要在新项目中使用 url-loader —— Webpack 5 的 type: 'asset' 配合 parser.dataUrlCondition.maxSize 提供了更简洁的替代方案。它原本用于小文件 Base64 内联以减少 HTTP 请求，但现代构建工具已内置此能力，无需额外依赖。

与file-loader类似的npm包

file-loader 是一个用于 Webpack 的加载器，它允许开发者将文件（如图像、字体等）作为模块导入到 JavaScript 代码中。使用 file-loader，您可以轻松地将文件打包到输出目录，并在构建过程中生成适当的 URL。它非常适合处理静态资源，使得在 Web 应用程序中使用这些资源变得更加简单和高效。

尽管 file-loader 提供了强大的功能，但还有其他一些替代方案可以实现类似的目的。以下是一些常见的替代方案：

  • copy-webpack-plugin 是一个 Webpack 插件，允许您将文件和目录复制到构建目录。与 file-loader 不同，copy-webpack-plugin 更加关注于复制文件，而不是将文件作为模块导入。它适用于需要将静态资源（如 HTML 文件、图像或其他文件）直接复制到输出目录的场景。这个插件非常灵活，能够处理各种文件类型，并且可以配置以满足特定的需求。

  • url-loader 是另一个 Webpack 加载器，它与 file-loader 类似，但提供了额外的功能。url-loader 可以将小于指定大小的文件转换为 Data URL，从而减少 HTTP 请求的数量。这使得在某些情况下，使用 url-loader 可以提高性能，尤其是在处理小型图像或字体时。url-loader 可以与 file-loader 一起使用，以便在需要时自动选择最佳的处理方式。

要查看 file-loader 与 copy-webpack-plugin 和 url-loader 之间的比较，请访问以下链接：比较 copy-webpack-plugin vs file-loader vs url-loader。

与url-loader类似的npm包

url-loader 是一个用于 Webpack 的加载器，它允许开发者将文件（如图像、字体等）转换为 Data URL，从而直接嵌入到 JavaScript 代码中。这种方式可以减少 HTTP 请求的数量，提高应用的加载速度。虽然 url-loader 提供了方便的文件处理方式，但在 Webpack 生态系统中还有其他一些替代方案可供选择。以下是几个替代方案：

  • file-loader 是一个简单的 Webpack 加载器，它将文件复制到输出目录并返回文件的 URL。与 url-loader 不同，file-loader 不会将文件转换为 Data URL，而是将其保留为独立的文件。这使得 file-loader 更适合处理较大的文件，或者当你希望在浏览器中以独立文件的形式访问它们时。
  • image-webpack-loader 是一个专门用于处理图像文件的 Webpack 加载器。它可以与其他加载器（如 file-loader 或 url-loader）结合使用，提供图像优化功能，如压缩和调整图像大小。对于需要处理大量图像并希望优化加载性能的项目，image-webpack-loader 是一个非常有用的工具。
  • raw-loader 是一个 Webpack 加载器，它允许开发者将文件内容作为字符串导入。这对于需要直接操作文件内容的情况非常有用，例如导入文本文件或其他非图像文件。虽然 raw-loader 的用途与 url-loader 不同，但在某些情况下，它可以作为处理文件的替代方案。

查看比较：比较 file-loader vs image-webpack-loader vs raw-loader vs url-loader。

file-loader的README

npm node deps tests coverage chat size

file-loader

The file-loader resolves import/require() on a file into a url and emits the file into the output directory.

Getting Started

To begin, you'll need to install file-loader:

$ npm install file-loader --save-dev

Import (or require) the target file(s) in one of the bundle's files:

file.js

import img from './file.png';

Then add the loader to your webpack config. For example:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
          },
        ],
      },
    ],
  },
};

And run webpack via your preferred method. This will emit file.png as a file in the output directory (with the specified naming convention, if options are specified to do so) and returns the public URI of the file.

ℹ️ By default the filename of the resulting file is the hash of the file's contents with the original extension of the required resource.

Options

name

Type: String|Function Default: '[contenthash].[ext]'

Specifies a custom filename template for the target file(s) using the query parameter name. For example, to emit a file from your context directory into the output directory retaining the full directory structure, you might use:

String

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          name: '[path][name].[ext]',
        },
      },
    ],
  },
};

Function

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          name(resourcePath, resourceQuery) {
            // `resourcePath` - `/absolute/path/to/file.js`
            // `resourceQuery` - `?foo=bar`

            if (process.env.NODE_ENV === 'development') {
              return '[path][name].[ext]';
            }

            return '[contenthash].[ext]';
          },
        },
      },
    ],
  },
};

ℹ️ By default the path and name you specify will output the file in that same directory, and will also use the same URI path to access the file.

outputPath

Type: String|Function Default: undefined

Specify a filesystem path where the target file(s) will be placed.

String

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          outputPath: 'images',
        },
      },
    ],
  },
};

Function

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          outputPath: (url, resourcePath, context) => {
            // `resourcePath` is original absolute path to asset
            // `context` is directory where stored asset (`rootContext`) or `context` option

            // To get relative path you can use
            // const relativePath = path.relative(context, resourcePath);

            if (/my-custom-image\.png/.test(resourcePath)) {
              return `other_output_path/${url}`;
            }

            if (/images/.test(context)) {
              return `image_output_path/${url}`;
            }

            return `output_path/${url}`;
          },
        },
      },
    ],
  },
};

publicPath

Type: String|Function Default: __webpack_public_path__+outputPath

Specifies a custom public path for the target file(s).

String

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          publicPath: 'assets',
        },
      },
    ],
  },
};

Function

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        loader: 'file-loader',
        options: {
          publicPath: (url, resourcePath, context) => {
            // `resourcePath` is original absolute path to asset
            // `context` is directory where stored asset (`rootContext`) or `context` option

            // To get relative path you can use
            // const relativePath = path.relative(context, resourcePath);

            if (/my-custom-image\.png/.test(resourcePath)) {
              return `other_public_path/${url}`;
            }

            if (/images/.test(context)) {
              return `image_output_path/${url}`;
            }

            return `public_path/${url}`;
          },
        },
      },
    ],
  },
};

postTransformPublicPath

Type: Function Default: undefined

Specifies a custom function to post-process the generated public path. This can be used to prepend or append dynamic global variables that are only available at runtime, like __webpack_public_path__. This would not be possible with just publicPath, since it stringifies the values.

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        loader: 'file-loader',
        options: {
          publicPath: '/some/path/',
          postTransformPublicPath: (p) => `__webpack_public_path__ + ${p}`,
        },
      },
    ],
  },
};

context

Type: String Default: context

Specifies a custom file context.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              context: 'project',
            },
          },
        ],
      },
    ],
  },
};

emitFile

Type: Boolean Default: true

If true, emits a file (writes a file to the filesystem). If false, the loader will return a public URI but will not emit the file. It is often useful to disable this option for server-side packages.

file.js

// bundle file
import img from './file.png';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              emitFile: false,
            },
          },
        ],
      },
    ],
  },
};

regExp

Type: RegExp Default: undefined

Specifies a Regular Expression to one or many parts of the target file path. The capture groups can be reused in the name property using [N] placeholder.

file.js

import img from './customer01/file.png';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              regExp: /\/([a-z0-9]+)\/[a-z0-9]+\.png$/i,
              name: '[1]-[name].[ext]',
            },
          },
        ],
      },
    ],
  },
};

ℹ️ If [0] is used, it will be replaced by the entire tested string, whereas [1] will contain the first capturing parenthesis of your regex and so on...

esModule

Type: Boolean Default: true

By default, file-loader generates JS modules that use the ES modules syntax. There are some cases in which using ES modules is beneficial, like in the case of module concatenation and tree shaking.

You can enable a CommonJS module syntax using:

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'file-loader',
            options: {
              esModule: false,
            },
          },
        ],
      },
    ],
  },
};

Placeholders

Full information about placeholders you can find here.

[ext]

Type: String Default: file.extname

The file extension of the target file/resource.

[name]

Type: String Default: file.basename

The basename of the file/resource.

[path]

Type: String Default: file.directory

The path of the resource relative to the webpack/config context.

[folder]

Type: String Default: file.folder

The folder of the resource is in.

[query]

Type: String Default: file.query

The query of the resource, i.e. ?foo=bar.

[emoji]

Type: String Default: undefined

A random emoji representation of content.

[emoji:<length>]

Type: String Default: undefined

Same as above, but with a customizable number of emojis

[hash]

Type: String Default: md4

Specifies the hash method to use for hashing the file content.

[contenthash]

Type: String Default: md4

Specifies the hash method to use for hashing the file content.

[<hashType>:hash:<digestType>:<length>]

Type: String

The hash of options.content (Buffer) (by default it's the hex digest of the hash).

digestType

Type: String Default: 'hex'

The digest that the hash function should use. Valid values include: base26, base32, base36, base49, base52, base58, base62, base64, and hex.

hashType

Type: String Default: 'md4'

The type of hash that the has function should use. Valid values include: md4, md5, sha1, sha256, and sha512.

length

Type: Number Default: undefined

Users may also specify a length for the computed hash.

[N]

Type: String Default: undefined

The n-th match obtained from matching the current file name against the regExp.

Examples

Names

The following examples show how one might use file-loader and what the result would be.

file.js

import png from './image.png';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: 'dirname/[contenthash].[ext]',
            },
          },
        ],
      },
    ],
  },
};

Result:

# result
dirname/0dcbbaa701328ae351f.png

file.js

import png from './image.png';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[sha512:hash:base64:7].[ext]',
            },
          },
        ],
      },
    ],
  },
};

Result:

# result
gdyb21L.png

file.js

import png from './path/to/file.png';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[path][name].[ext]?[contenthash]',
            },
          },
        ],
      },
    ],
  },
};

Result:

# result
path/to/file.png?e43b20c069c4a01867c31e98cbce33c9

CDN

The following examples show how to use file-loader for CDN uses query params.

file.js

import png from './directory/image.png?width=300&height=300';

webpack.config.js

module.exports = {
  output: {
    publicPath: 'https://cdn.example.com/',
  },
  module: {
    rules: [
      {
        test: /\.(png|jpe?g|gif)$/i,
        use: [
          {
            loader: 'file-loader',
            options: {
              name: '[path][name].[ext][query]',
            },
          },
        ],
      },
    ],
  },
};

Result:

# result
https://cdn.example.com/directory/image.png?width=300&height=300

Dynamic public path depending on environment variable at run time

An application might want to configure different CDN hosts depending on an environment variable that is only available when running the application. This can be an advantage, as only one build of the application is necessary, which behaves differently depending on environment variables of the deployment environment. Since file-loader is applied when compiling the application, and not when running it, the environment variable cannot be used in the file-loader configuration. A way around this is setting the __webpack_public_path__ to the desired CDN host depending on the environment variable at the entrypoint of the application. The option postTransformPublicPath can be used to configure a custom path depending on a variable like __webpack_public_path__.

main.js

const assetPrefixForNamespace = (namespace) => {
  switch (namespace) {
    case 'prod':
      return 'https://cache.myserver.net/web';
    case 'uat':
      return 'https://cache-uat.myserver.net/web';
    case 'st':
      return 'https://cache-st.myserver.net/web';
    case 'dev':
      return 'https://cache-dev.myserver.net/web';
    default:
      return '';
  }
};
const namespace = process.env.NAMESPACE;

__webpack_public_path__ = `${assetPrefixForNamespace(namespace)}/`;

file.js

import png from './image.png';

webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.(png|jpg|gif)$/i,
        loader: 'file-loader',
        options: {
          name: '[name].[contenthash].[ext]',
          outputPath: 'static/assets/',
          publicPath: 'static/assets/',
          postTransformPublicPath: (p) => `__webpack_public_path__ + ${p}`,
        },
      },
    ],
  },
};

Result when run with NAMESPACE=prod env variable:

# result
https://cache.myserver.net/web/static/assets/image.somehash.png

Result when run with NAMESPACE=dev env variable:

# result
https://cache-dev.myserver.net/web/static/assets/image.somehash.png

Contributing

Please take a moment to read our contributing guidelines if you haven't yet done so.

CONTRIBUTING

License

MIT

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. For more details, please refer to our Terms & Privacy.