file-loader vs url-loader vs raw-loader vs image-webpack-loader
Webpack 檔案處理器
file-loaderurl-loaderraw-loaderimage-webpack-loader

Webpack 檔案處理器

這些 NPM 套件用於 Webpack 中的檔案處理,幫助開發者在構建過程中有效地管理和處理各種檔案類型。它們各自有不同的功能和使用場景,適合不同的需求和性能考量。

npm下載趨勢

3 年

GitHub Stars 排名

統計詳情

套件
下載數
Stars
大小
Issues
發布時間
許可
file-loader12,084,3851,842-16 年前MIT
url-loader6,710,5691,394-46 年前MIT
raw-loader4,828,551838-56 年前MIT
image-webpack-loader84,7972,0083.56 MB81-MIT

功能比較: file-loader vs url-loader vs raw-loader vs image-webpack-loader

檔案處理方式

  • file-loader:

    file-loader 將檔案複製到輸出目錄並返回其 URL,適合處理靜態資源,簡單易用。

  • url-loader:

    url-loader 根據檔案大小決定使用 base64 編碼還是 file-loader,對於小型圖片特別有效,能夠減少 HTTP 請求。

  • raw-loader:

    raw-loader 將檔案內容作為字串導入,適合需要直接操作檔案內容的場景,如模板或配置檔案。

  • image-webpack-loader:

    image-webpack-loader 專門用於圖片的優化,支持多種圖片格式,能夠在編譯過程中自動進行壓縮和轉換。

性能優化

  • file-loader:

    file-loader 本身不進行任何優化,僅負責檔案的複製和 URL 返回,性能依賴於其他優化工具。

  • url-loader:

    url-loader 能夠根據檔案大小選擇處理方式,對於小檔案使用 base64 編碼可以減少請求數量,提升性能。

  • raw-loader:

    raw-loader 不涉及性能優化,主要用於直接導入檔案內容,性能影響較小。

  • image-webpack-loader:

    image-webpack-loader 提供多種圖片優化選項,如壓縮、格式轉換等,能顯著減少圖片大小,提高加載速度。

使用場景

  • file-loader:

    適合用於需要將靜態資源如字體、音視頻檔案等複製到輸出目錄的情況。

  • url-loader:

    適合用於需要靈活處理小型圖片或資源的情況,能夠根據檔案大小自動選擇處理方式。

  • raw-loader:

    適合用於需要將檔案內容作為字串使用的情況,如模板引擎或配置檔案。

  • image-webpack-loader:

    適合用於需要對圖片進行優化的項目,特別是對於大型網站或應用程式的圖片管理。

配置複雜度

  • file-loader:

    file-loader 配置簡單,通常只需要指定輸出目錄即可。

  • url-loader:

    url-loader 配置相對簡單,但需要設置檔案大小的閾值以決定使用 base64 還是 file-loader。

  • raw-loader:

    raw-loader 配置簡單,通常只需指定要導入的檔案路徑。

  • image-webpack-loader:

    image-webpack-loader 配置較為複雜,需要根據不同的需求設置多種優化選項。

學習曲線

  • file-loader:

    file-loader 的學習曲線平緩,易於上手,適合初學者。

  • url-loader:

    url-loader 的學習曲線相對平緩,但需要理解 base64 編碼的概念。

  • raw-loader:

    raw-loader 的學習曲線平緩,易於理解和使用。

  • image-webpack-loader:

    image-webpack-loader 需要對圖片處理有一定了解,學習曲線相對較陡。

如何選擇: file-loader vs url-loader vs raw-loader vs image-webpack-loader

  • file-loader:

    選擇 file-loader 當你需要將檔案複製到輸出目錄並返回其 URL 時,這對於處理靜態資源如字體或影片檔案特別有用。

  • url-loader:

    選擇 url-loader 當你希望根據檔案大小自動選擇是將檔案作為 URL 嵌入還是使用 file-loader 進行處理時,這對於需要靈活處理小型圖片或資源的情況非常適合。

  • raw-loader:

    選擇 raw-loader 當你需要將檔案內容作為字串導入時,這對於處理文本檔案或需要直接操作檔案內容的情況特別有用。

  • image-webpack-loader:

    選擇 image-webpack-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