Загрузчик файлов

file-loader разрешает import/require() для файла в URL и выводит файл в выходной каталог.

Начало работы

Для начала вам необходимо установить file-loader:

$ npm install file-loader --save-dev

Импортируйте (или require) целевой файл(ы) в один из файлов пакета:

file.js

import img from './file.png';

Затем добавьте загрузчик в свою конфигурацию webpack. Например:

webpack.config.js

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

И запустите webpack с помощью вашего предпочитаемого метода. Это выведет file.png в качестве файла в выходной каталог (с указанной схемой именования, если такие опции заданы) и вернёт общедоступный URI файла.

ℹ️ По умолчанию имя результирующего файла — это хэш содержимого файла с оригинальным расширением требуемого ресурса.

Параметры

name

Тип: String|Function По умолчанию: '[contenthash].[ext]'

Указывает пользовательскую шаблон для именования целевого файла(ов) с использованием параметра запроса name. Например, для вывода файла из каталога context в выходной каталог, сохраняя полную структуру каталогов, можно использовать:

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(file) {
            if (process.env.NODE_ENV === 'development') {
              return '[path][name].[ext]';
            }

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

ℹ️ По умолчанию, путь и имя, которые вы указываете, выведут файл в этот же каталог и также будут использовать тот же путь URI для доступа к файлу.

outputPath

Тип: String|Function По умолчанию: undefined

Указывает путь к файловой системе, где будут размещены целевые файлы(ы).

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

Тип: String|Function По умолчанию: __webpack_public_path__

Указывает пользовательский общедоступный путь для целевого файла(ов).

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

Тип: Function По умолчанию: undefined

Указывает пользовательскую функцию для последующей обработки сгенерированного общего пути. Это может быть использовано для добавления или вставки динамических глобальных переменных, доступных только во время выполнения, таких как __webpack_public_path__. Это не было бы возможно только с publicPath, так как она строит значения.

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

Тип: String По умолчанию: context

Указывает пользовательский контекст файла.

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

emitFile

Тип: Boolean По умолчанию: true

Если true, выводит файл (записывает файл в файловую систему). Если false, загрузчик вернёт общий URI, но не выведет файл. Это часто полезно для отключения этой опции для серверных пакетов.

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

Тип: RegExp По умолчанию: undefined

Указывает регулярное выражение для одной или нескольких частей пути целевого файла. Группы захвата могут быть повторно использованы в свойстве name с помощью [N] заместителя.

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]',
            },
          },
        ],
      },
    ],
  },
};

ℹ️ Если используется [0], он будет заменён всей проверенной строкой, тогда как [1] будет содержать первую захватывающую скобку вашего регулярного выражения и так далее...

Заменители

Полная информация о заменителях доступна здесь.

[ext]

Тип: String По умолчанию: file.extname

Расширение файла целевого файла/ресурса.

[name]

Тип: String По умолчанию: file.basename

Имя файла/ресурса.

[path]

Тип: String По умолчанию: file.directory

Путь к ресурсу относительно webpack/конфигурации context.

[folder]

Тип: String По умолчанию: file.folder

Каталог, в котором находится ресурс.

[emoji]

Тип: String По умолчанию: undefined

Случайное изображение эмодзи, представляющее content.

[emoji:<length>]

Тип: String По умолчанию: undefined

То же самое, но с настраиваемым количеством эмодзи

[hash]

Тип: String По умолчанию: md5

Указывает метод хэширования для хэширования содержимого файла.

[contenthash]

Тип: String По умолчанию: md5

Указывает метод хэширования для хэширования содержимого файла.

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

Тип: String

Хэш options.content (Buffer) (по умолчанию — шестнадцатеричный дайджест хэша).

digestType

Тип: String По умолчанию: 'hex'

Дайджест хэш-функции. Допустимые значения включают: base26, base32, base36, base49, base52, base58, base62, base64 и hex.

hashType

Тип: String По умолчанию: 'md5'

Тип хэша, который должна использовать функция хэширования. Допустимые значения включают: md5, sha1, sha256, и sha512.

length

Тип: Number По умолчанию: undefined

Пользователь также может указать длину вычисленного хэша.

[N]

Тип: String По умолчанию: undefined

n-ый совпадение, полученное при сопоставлении текущего имени файла с regExp.

Примеры

Имена

Следующие примеры показывают, как можно использовать file-loader и какой будет результат.

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
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
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
path/to/file.png?e43b20c069c4a01867c31e98cbce33c9

Динамический общедоступный путь в зависимости от переменной окружения во время выполнения

Приложение может захотеть настроить разные хосты CDN в зависимости от переменной окружения, которая доступна только при запуске приложения. Это может быть преимуществом, так как требуется только один сборка приложения, который ведёт себя по-разному в зависимости от переменных окружения среды развертывания. Поскольку загрузчик файлов применяется при компиляции приложения, а не при его запуске, переменная окружения не может быть использована в конфигурации загрузчика файлов. Способ обойти это — установить __webpack_public_path__ на желаемый хост CDN в зависимости от переменной окружения в точке входа приложения. Опция postTransformPublicPath может быть использована для настройки пользовательского пути в зависимости от переменной, такой как __webpack_public_path__.

main.js

const namespace = process.env.NAMESPACE;
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 '';
  }
};
__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}`,
        },
      },
    ],
  },
};

Результат при запуске с NAMESPACE=prod переменной окружения:

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

Результат при запуске с NAMESPACE=dev переменной окружения:

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

Содействие

Пожалуйста, посмотрите наши рекомендации по участию в разработке, если вы ещё этого не сделали.

CONTRIBUTING

Лицензия

MIT