命名器

命名器插件确定包的输出文件名。命名器按管道运行，直到其中一个返回结果。返回的文件路径应相对于目标 distDir。有关详细信息，请参阅 目标。

覆盖特定包的名称

命名器插件的常见用例是覆盖 Parcel 对特定包的默认命名方案。命名器在不处理包时可以返回 null，以便管道中的下一个命名器可以处理它。有关此工作原理的详细信息，请参阅 Parcel 配置文档中的 命名器。

此示例将所有 png 和 jpg 文件放置到与原始文件名相同的 images 文件夹中。

import {Namer} from '@parcel/plugin';
import path from 'path';

export default new Namer({
  name({bundle}) {
    if (bundle.type === 'png' || bundle.type === 'jpg') {
      let filePath = bundle.getMainEntry().filePath;
      return `images/${path.basename(filePath)}`;
    }

    // Allow the next namer to handle this bundle.
    return null;
  }
});

内容哈希

包含包内容的哈希值是生产构建的重要优化，它使浏览器能够无限期地缓存加载的文件。当包的内容发生变化时，其文件名也会发生变化，这充当缓存失效机制。有关此内容的详细信息，请参阅 内容哈希 文档。

在命名包时，最终内容尚不清楚，因此 Parcel 在每个 Bundle 对象上提供了一个 hashReference 属性。这是一个不透明的占位符值，稍后将在写入最终包时替换为实际哈希值。在返回的包名称中使用它来包含内容哈希值。

在包含哈希值之前，请务必检查 bundle.needsStableName 属性。当此值为 true 时，依赖项期望包的文件名随着时间的推移保持一致。例如，服务工作者要求其 URL 永远不会改变，并且用户期望可见 URL（如 HTML 页面）是可读的并且保持一致。

import {Namer} from '@parcel/plugin';

export default new Namer({
  name({bundle}) {
    let name = yourNamingFunction(bundle);
    if (!bundle.needsStableName) {
      name += "." + bundle.hashReference;
    }
    return name + "." + bundle.type;
  }
});

目标

命名器插件还应尊重与包关联的 Target。目标 允许用户在 package.json 中配置入口包的输出文件名。如果包位于入口包组中，并且包含入口资产，则命名器插件应在可用时使用 bundle.target.distEntry 作为输出文件名。

import {Namer} from '@parcel/plugin';

export default new Namer({
  name({bundle, bundleGraph}) {
    let bundleGroup = bundleGraph
      .getBundleGroupsContainingBundle(bundle)[0];
    let isEntry = bundleGraph.isEntryBundleGroup(bundleGroup);
    let bundleGroupBundles = bundleGraph
      .getBundlesInBundleGroup(bundleGroup);
    let mainBundle = bundleGroupBundles.find(b =>
      b.getEntryAssets()
       .some(a => a.id === bundleGroup.entryAssetId),
  );

    if (
      isEntry && 
      bundle.id === mainBundle.id && 
      bundle.target?.distEntry
    ) {
      return bundle.target.distEntry;
    }

    // ...
  }
});

加载配置

从用户的项目加载配置应在命名器插件的 loadConfig 方法中完成。有关如何执行此操作的详细信息，请参阅 加载配置。

相关 API

type Namer<ConfigType> = {|

  loadConfig?: ({|
    config: Config,
    options: PluginOptions,
    logger: PluginLogger,
  |}) => Promise<ConfigType> | ConfigType,

  name({|
    bundle: Bundle,
    bundleGraph: BundleGraph<Bundle>,
    config: ConfigType,
    options: PluginOptions,
    logger: PluginLogger,
  |}): Async<?FilePath>,

|}