插件

Parcel 对于许多零配置项目来说是开箱即用的。但如果你想要更多控制，或者需要扩展或覆盖 Parcel 的默认设置，你可以通过在项目中创建 .parcelrc 文件来实现。

¥Parcel works out of the box for many projects with zero configuration. But if you want more control, or need to extend or override Parcel’s defaults, you can do so by creating a .parcelrc file in your project.

Parcel 的设计非常模块化。Parcel 核心本身几乎不专门用于构建 JavaScript 或网页 - 所有行为都是通过插件指定的。构建的每个阶段都有特定的插件类型，因此你可以自定义几乎所有内容。

¥Parcel is designed to be very modular. Parcel core itself is almost not specific to building JavaScript or web pages – all behavior is specified via plugins. There are specific plugin types for each phase of a build, so you can customize just about everything.

.parcelrc

Parcel 配置在 .parcelrc 文件中指定。它是用 JSON5 编写的，类似于 JSON，但支持注释、不带引号的键、尾随逗号和其他功能。

¥Parcel configuration is specified in a .parcelrc file. It is written in JSON5, which is similar to JSON but supports comments, unquoted keys, trailing commas, and other features.

扩展配置

¥Extending configs

Parcel 的默认配置在 @parcel/config-default 中指定。大多数时候，你需要在自己的 Parcel 配置中扩展它。为此，请使用 .parcelrc 中的 extends 字段。

¥Parcel’s default config is specified in @parcel/config-default. Most of the time, you'll want to extend it in your own Parcel config. To do this, use the extends field in your .parcelrc.

{
  "extends": "@parcel/config-default"
}

你还可以通过传递数组来扩展多个配置。配置按照指定的顺序合并。

¥You may also extend multiple configs by passing an array. Configs are merged in the order they are specified.

{
  "extends": ["@parcel/config-default", "@company/parcel-config"]
}

你还可以使用相对路径引用项目中的另一个配置。

¥You can also reference another config in your project using a relative path.

{
  "extends": "../.parcelrc"
}

扩展配置还可以扩展其他配置，从而形成配置链。

¥Extended configs may also extend other configs, which forms a config chain.

通配映射

¥Glob maps

.parcelrc 中的许多字段（如 transformers 或 packagers）使用对象作为 glob 到插件名称的映射。这使你可以通过文件扩展名、文件路径甚至特定文件名来配置 Parcel 的行为。Glob 相对于包含 .parcelrc 的目录进行匹配。

¥Many fields in .parcelrc like transformers or packagers use objects as maps of globs to plugin names. This lets you configure Parcel’s behavior by file extension, file path, or even a specific file name. Globs are matched relative to the directory containing the .parcelrc.

glob 映射中的字段顺序定义了在针对它们测试文件名时它们的优先级。这使你可以为项目中的某些文件（例如特定目录中的文件）配置不同的行为。

¥The order of fields in glob maps defines their priority when a file name is being tested against them. This lets you configure different behavior for certain files within your project, such as files in a specific directory.

{
  "transformers": {
    "icons/*.svg": ["highest-priority"],
    "*.svg": ["lowest-priority"]
  }
}

在这里，如果我们试图找到文件 icons/home.svg 的转换，我们将沿着 glob 向下查找，直到找到匹配项，即 icons/*.svg。我们永远无法达到 *.svg。

¥Here if we are trying to find a transform for the file icons/home.svg, we'll work our way down the globs until we find a match, which would be icons/*.svg. We never reach *.svg.

检查当前配置中的所有 glob 后，Parcel 将回退到任何扩展配置中定义的 glob。

¥Once all of the globs in the current config are checked, Parcel falls back to the globs defined in any extended configs.

管道

¥Pipelines

.parcelrc 中的许多字段（如 transformers、optimizers 和 reporters）接受一系列串联运行的插件。这些称为管道。

¥Many fields in .parcelrc like transformers, optimizers, and reporters accept an array of plugins which run in series. These are called pipelines.

如果你想定义一个较高优先级的管道来扩展较低优先级的管道而不是覆盖它，则可以使用特殊的 "..." 语法来实现。将其添加到管道中以在其中嵌入下一个优先级管道。你可以将其插入管道的开头、结尾甚至中间，这样你就可以完全控制管道的扩展方式。

¥If you’d like to define a higher priority pipeline that extends a lower priority one rather than overriding it, you can use the special "..." syntax to do so. Add this within a pipeline to embed the next priority pipeline within it. You can insert it at the beginning, end, or even in the middle of a pipeline, which gives you full control over how pipelines are extended.

{
  "transformers": {
    "icons/*.svg": ["@company/parcel-transformer-svg-icons", "..."],
    "*.svg": ["@parcel/transformer-svg"]
  }
}

在上面的例子中，当处理 icons/home.svg 时，我们先运行 @company/parcel-transformer-svg-icons，然后运行 @parcel/transformer-svg。

¥In the above example, when processing icons/home.svg, we first run @company/parcel-transformer-svg-icons and then @parcel/transformer-svg.

这也适用于已扩展的配置。如果使用 "..." 并且当前配置中没有定义较低优先级的管道，则 Parcel 将回退到扩展配置中定义的管道。

¥This also applies to configs that have been extended. If a "..." is used and there are no lower priority pipelines defined in the current config, Parcel falls back to pipelines defined in the extended configs.

由于 @parcel/transformer-svg 包含在默认配置中，因此上面的示例可以重写如下：

¥Since @parcel/transformer-svg is included in the default config, the above example could be rewritten like this:

{
  "extends": "@parcel/config-default",
  "transformers": {
    "icons/*.svg": ["@company/parcel-transformer-svg-icons", "..."]
  }
}

命名管道

¥Named pipelines

除了基于 glob 的管道之外，Parcel 还支持命名管道，这使你能够以多种方式导入同一文件。命名管道在 .parcelrc 中定义，就像普通管道一样，但在 glob 的开头包含 URL 方案。

¥In addition to glob-based pipelines, Parcel supports named pipelines, which enable you to import a the same file in multiple ways. Named pipelines are defined in .parcelrc just like normal pipelines, but include a URL scheme at the start of the glob.

例如，默认情况下，导入图片通常会返回外部文件的 URL，但你可以使用默认 Parcel 配置中定义的 data-url: 命名管道将其内联为数据 URL。详情请参见 打包内联。

¥For example, by default, importing an image normally returns a URL to an external file, but you could use the data-url: named pipeline defined in the default Parcel config to inline it as a data URL instead. See Bundle inlining for details.

.logo {
  background: url(data-url:./logo.png);
}

你还可以定义自己的命名管道。例如，你可以定义一个 arraybuffer: 命名管道，该管道允许你将文件导入为 ArrayBuffer。* glob 与本示例中的任何文件匹配，但你也可以使用更具体的 glob。"..." 语法用于允许 Parcel 在运行 parcel-transformer-arraybuffer 插件将其转换为 ArrayBuffer 之前像平常一样处理文件。

¥You can also define your own named pipelines. For example, you could define an arraybuffer: named pipeline that allows you to import a file as an ArrayBuffer. The * glob matches any file in this example, but you could also use a more-specific glob. The "..." syntax is used to allow Parcel to process the file as it normally would before running the parcel-transformer-arraybuffer plugin to convert it to an ArrayBuffer.

{
  "extends": "@parcel/config-default",
  "transformers": {
    "arraybuffer:*": ["...", "parcel-transformer-arraybuffer"]
  }
}

import buffer from 'arraybuffer:./file.png';

转换器和优化器管道支持命名管道。对于转换器，管道在引用资源的依赖中指定。对于优化器来说，它继承自打包包的入口资源。

¥Named pipelines are supported for transformer and optimizer pipelines. For transformers, the pipeline is specified in the dependency that referenced the asset. For optimizers, it is inherited from the entry asset of the bundle.

插件

¥Plugins

Parcel 支持许多不同类型的插件，它们作为构建的一部分执行特定任务。.parcelrc 中使用插件的 NPM 包名称来引用插件。

¥Parcel supports many different kinds of plugins which perform a specific task as part of your build. Plugins are referenced in your .parcelrc using their NPM package names.

转换器

¥Transformers

查找 Transformer 插件

¥Find Transformer plugins

转换器 插件转换单个资源以对其进行编译、发现依赖或将其转换为不同的格式。它们使用 通配映射 中的 .parcelrc 进行配置。多个转换器可以使用 pipelines 在同一资源上串联运行，并且支持 命名管道 以允许在同一项目中以多种不同方式编译同一文件。"..." 语法可用于扩展文件的默认转换器。

¥Transformer plugins transform a single asset to compile it, discover dependencies, or convert it to a different format. They are configured using a glob map in .parcelrc. Multiple transformers may run in series over the same asset using pipelines, and named pipelines are supported to allow compiling the same file in multiple different ways within the same project. The "..." syntax can be used to extend the default transformers for a file.

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.svg": ["...", "@parcel/transformer-svg-react"]
  }
}

编译资源时，其文件类型可能会发生变化。例如，编译 TypeScript 时，资源类型从 ts 或 tsx 更改为 js。发生这种情况时，Parcel 会重新评估应如何进一步处理资源，并通过 .js 文件的匹配管道运行它。

¥When compiling an asset, its file type may change. For example, when compiling TypeScript, the asset’s type changes from ts or tsx to js. When this happens, Parcel re-evaluates how the asset should be further processed, and runs it through the matching pipeline for .js files.

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.{ts,tsx}": ["@parcel/transformer-typescript-tsc"]
  }
}

解析器

¥Resolvers

查找解析器插件

¥Find Resolver plugins

解析器 插件负责将依赖说明符转换为将由转换器处理的完整文件路径。有关其工作原理的详细信息，请参阅 依赖解析。解析器是使用 .parcelrc 中的一系列插件名称进行配置的。解析通过插件列表进行，直到其中一个返回结果。

¥Resolver plugins are responsible for turning a dependency specifier into a full file path that will be processed by transformers. See Dependency resolution for details on how this works. Resolvers are configured using an array of plugin names in .parcelrc. Resolution proceeds through the list of plugins until one of them returns a result.

"..." 语法可用于扩展默认解析器。这允许你覆盖某些依赖的解析，但对于其他依赖则回退到默认值。通常，你需要在运行默认解析器之前添加自定义解析器。

¥The "..." syntax can be used to extend the default resolvers. This allows you to override the resolution for certain dependencies, but fall back to the default for others. Generally, you'll want to add your custom resolvers before running the default ones.

{
  "extends": "@parcel/config-default",
  "resolvers": ["@company/parcel-resolver", "..."]
}

如果省略 "..."，你的解析器必须能够处理所有依赖，否则解析将失败。

¥If "..." is omitted, your resolver must be able to handle all dependencies or resolution will fail.

打包器（实验性）

¥Bundler (experimental)

查找 Bundler 插件

¥Find Bundler plugins

打包器 插件负责将资源分组到打包包中。可以通过在 .parcelrc 中指定插件名称来配置打包器。

¥A Bundler plugin is responsible for grouping assets together into bundles. The bundler can be configured by specifying a plugin name in .parcelrc.

{
  "extends": "@parcel/config-default",
  "bundler": "@company/parcel-bundler"
}

运行时（实验）

¥Runtimes (experimental)

查找运行时插件

¥Find Runtime plugins

运行 插件允许你将资源注入到打包包中。可以使用 .parcelrc 中的一系列插件名称来配置它们。此列表中的所有运行时插件都在每个包上运行。"..." 语法可用于扩展默认运行时间。

¥Runtime plugins allow you to inject assets into bundles. They can be configured using an array of plugin names in .parcelrc. All runtime plugins in this list are run over each bundle. The "..." syntax can be used to extend the default runtimes.

{
  "extends": "@parcel/config-default",
  "runtimes": ["@company/parcel-runtime", "..."]
}

如果省略 "..."，则不会运行默认运行时。这可能会破坏一些东西，因为许多 Parcel 功能依赖于默认运行时。

¥If "..." is omitted, the default runtimes will not be run. This will probably break things, as many Parcel features rely on the default runtimes.

命名者

¥Namers

查找 Namer 插件

¥Find Namer plugins

命名 插件确定打包包的输出文件名。它们是使用 .parcelrc 中的一系列插件名称进行配置的。命名将通过命名者列表进行，直到其中之一返回结果。

¥Namer plugins determine the output filename for a bundle. They are configured using an array of plugin names in .parcelrc. Naming proceeds through the list of namers until one of them returns a result.

"..." 语法可用于扩展默认命名器。这允许你覆盖某些打包包的命名，但对其他打包包则回退到默认值。通常，你需要在运行默认命名器之前添加自定义命名器。

¥The "..." syntax can be used to extend the default namers. This allows you to override naming of certain bundles, but fall back to the default for others. Generally, you'll want to add your custom namers before running the default ones.

{
  "extends": "@parcel/config-default",
  "namers": ["@company/parcel-namer", "..."]
}

如果省略 "..."，你的命名者必须能够处理所有包的命名，否则构建将失败。

¥If "..." is omitted, your namer must be able to handle naming all bundles or the build will fail.

包

¥Packagers

查找 Packager 插件

¥Find Packager plugins

打包器 插件负责将打包包中的所有资源组合到一个输出文件中。它们使用 通配映射 中的 .parcelrc 进行配置。Glob 与包的输出文件名进行匹配。单个打包器插件可以配置为每个包运行。

¥Packager plugins are responsible for combining all of the assets in a bundle together into an output file. They are configured using a glob map in .parcelrc. Globs are matched against the output filename of a bundle. A single packager plugin may be configured to run per bundle.

{
  "extends": "@parcel/config-default",
  "packagers": {
    "*.{jpg,png}": "@company/parcel-packager-image-sprite"
  }
}

优化器

¥Optimizers

查找优化器插件

¥Find Optimizer plugins

优化器 插件与 Transformer 类似，但它们接受打包包而不是单个资源。它们使用 通配映射 中的 .parcelrc 进行配置。多个优化器可以使用 pipelines 在同一包上串联运行，并且支持 命名管道 以允许在同一项目中以多种不同方式编译同一包。"..." 语法可用于扩展打包包的默认优化器。

¥Optimizer plugins are similar to transformers but they accept a bundle instead of a single asset. They are configured using a glob map in .parcelrc. Multiple optimizers may run in series over the same bundle using pipelines, and named pipelines are supported to allow compiling the same bundle in multiple different ways within the same project. The "..." syntax can be used to extend the default optimizers for a bundle.

{
  "extends": "@parcel/config-default",
  "optimizers": {
    "*.js": ["@parcel/optimizer-esbuild"]
  }
}

压缩器

¥Compressors

查找压缩器插件

¥Find Compressor plugins

将最终包写入磁盘时使用 压缩器 插件，并可能以某种方式对其进行压缩或编码（例如 Gzip）。它们使用 通配映射 中的 .parcelrc 进行配置。使用 pipelines 可以在同一个包上运行多个压缩器。每个压缩器插件都会生成一个要并行写入的附加文件，例如 bundle.js、bundle.js.gz 和 bundle.js.br。"..." 语法可用于扩展包的默认压缩器。

¥Compressor plugins are used when writing a final bundle to disk and may compress or encode it in some way (e.g. Gzip). They are configured using a glob map in .parcelrc. Multiple compressors may run over the same bundle using pipelines. Each compressor plugin produces an additional file to be written in parallel, for example bundle.js, bundle.js.gz and bundle.js.br. The "..." syntax can be used to extend the default compressors for a bundle.

{
  "extends": "@parcel/config-default",
  "compressors": {
    "*.{js,html,css}": [
      "...",
      "@parcel/compressor-gzip",
      "@parcel/compressor-brotli"
    ]
  }
}

报告器

¥Reporters

查找 Reporter 插件

¥Find Reporter plugins

报告器 插件在整个构建过程中发生事件时接收来自 Parcel 的事件。例如，报告者可以将状态信息写入标准输出、运行开发服务器或在构建结束时生成包分析报告。报告器使用 .parcelrc 中的一系列包名称进行配置。此列表中的所有报告器都会针对每个构建事件运行。"..." 语法可用于扩展默认报告器。

¥Reporter plugins receive events from Parcel as they happen throughout the build process. For example, reporters may write status information to stdout, run a dev server, or generate a bundle analysis report at the end of a build. Reporters are configured using an array of package names in .parcelrc. All reporters in this list are run for each build event. The "..." syntax can be used to extend the default reporters.

{
  "extends": "@parcel/config-default",
  "reporters": ["...", "@parcel/reporter-bundle-analyzer"]
}

你不经常使用的报告器也可以使用 --reporter 选项在 CLI 上指定，或者使用 additionalReporters 选项通过 API 指定。报告器指定的 .parcelrc 始终运行。

¥Reporters that you use infrequently may also be specified on the CLI using the --reporter option, or via the API using the additionalReporters option. Reporters specified in .parcelrc always run.

本地插件

¥Local plugins

大多数 Parcel 插件都是 NPM 包。这意味着它们有一个 package.json，它声明了它们兼容的 Parcel 版本，以及它们可能具有的任何依赖。它们还必须遵循命名系统以确保清晰度。

¥Most parcel plugins are NPM packages. This means they have a package.json which declares the version of Parcel they are compatible with, along with any dependencies they may have. They must also follow a naming system to ensure clarity.

通常，Parcel 插件会发布到 NPM 注册表或内部公司注册表（例如 Artifactory）。这鼓励插件与社区或公司内的项目共享，以避免重复。

¥Usually, Parcel plugins are published to the NPM registry, or to an internal company registry (e.g. Artifactory). This encourages plugins to be shared with the community or across projects within your company to avoid duplication.

但是，在开发插件时，直接在项目中运行它而不先发布它可能会很有用。有几种方法可以做到这一点。

¥However, when developing a plugin, it can be useful to run it directly in your project without publishing it first. There are a few ways of doing this.

相对文件路径

¥Relative file paths

插件可以作为它们所使用的 .parcelrc 配置文件的相对路径来引用。这些可能是 CommonJS 或 ESM 模块，由使用 .mjs 或 .cjs 扩展或最近的 package.json 中的 "type": "module" 字段确定（与 Node 加载模块的方式相同）。

¥Plugins may be referenced as relative paths from the .parcelrc config file they are used in. These may be CommonJS or ESM modules, as determined using the .mjs or .cjs extension, or the "type": "module" field in the nearest package.json (the same way Node loads modules).

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.js": ["./my-local-plugin.mjs", "..."]
  }
}

Yarn 和 NPM 工作区

¥Yarn and NPM workspaces

使用本地插件的另一种方法是通过 Yarn 工作区 或 NPM 工作区 使用 monorepo 设置。这允许你像依赖已发布的包一样依赖存储库中的其他包。为此，请设置如下项目结构：

¥Another way to use local plugins is to use a monorepo setup via Yarn Workspaces or NPM Workspaces. This allows you to depend on other packages within your repo the same way you depend on published packages. To do this, set up a project structure like this:

project
├── .parcelrc
├── package.json
└── packages
    ├── app
    │   └── package.json
    └── parcel-transformer-foo
        ├── package.json
        └── src
            └── FooTransformer.js

在你的根 package.json 中，使用 workspaces 字段来引用你的包。

¥In your root package.json, use the workspaces field to reference your packages.

{
  "name": "my-project",
  "private": true,
  "workspaces": ["packages/*"]
}

然后，在 .parcelrc 中，你可以像引用已发布的包一样引用 parcel-transformer-foo。每当你更新插件的代码时，Parcel 都会重建你的项目。

¥Then, in your .parcelrc you can reference parcel-transformer-foo as you would a published package. Whenever you update the code for your plugin, Parcel will rebuild your project.

你还可以选择将应用保留在根目录中（例如，在 src 文件夹中）而不是在 packages/app 中。

¥You can also choose to keep your app in the root (e.g. in a src folder) rather than inside packages/app.

link: 协议

¥The link: protocol

Yarn 支持使用 link: 协议定义依赖，将本地目录引用为包。例如，你可以设置如下项目结构：

¥Yarn supports defining dependencies using the link: protocol to reference local directories as packages. For example, you could set up a project structure like this:

project
├── .parcelrc
├── package.json
├── src
│   └── index.html
└── parcel-transformer-foo
    ├── package.json
    └── src
        └── FooTransformer.js

在根 package.json 中，你可以使用 link: 协议定义对 parcel-transformer-foo 包的依赖。

¥In your root package.json, you can define a dependency on the parcel-transformer-foo package using the link: protocol.

{
  "name": "my-project",
  "dependencies": {
    "parcel": "^2.0.0",
    "parcel-transformer-foo": "link:./parcel-transformer-foo"
  }
}

然后，在 .parcelrc 中，你可以像引用已发布的包一样引用 parcel-transformer-foo。每当你更新插件的代码时，Parcel 都会重建你的项目。

¥Then, in your .parcelrc you can reference parcel-transformer-foo as you would a published package. Whenever you update the code for your plugin, Parcel will rebuild your project.