目标

Parcel 可以同时以多种不同的方式编译源代码。这些称为目标。例如，你可以有一个针对较新浏览器的“现代”目标和针对较旧浏览器的“旧版”目标。

¥Parcel can compile your source code in multiple different ways simultaneously. These are called targets. For example, you could have a “modern” target that targets newer browsers and a “legacy” target for older browsers.

入口

¥Entries

“条目”是构建源代码时 Parcel 启动的文件。它们可以在 CLI 上指定，或使用 package.json 中的 source 字段。

¥“Entries” are the files that Parcel starts at when building your source code. They can be specified on the CLI, or using the source field in package.json.

`$ parcel <entries>`

可以在 CLI 上为任何 Parcel 命令指定一个或多个入口文件。

¥One or more entry files can be specified on the CLI to any Parcel command.

$ parcel src/a.html src/b.html

入口可以指定为 glob 以一次匹配多个文件。请务必将 glob 用单引号括起来，以确保 glob 不会被你的 shell 解析并直接传递给 Parcel。这确保了 Parcel 可以自动拾取与 glob 匹配的新创建的文件，而无需重新启动。

¥Entries may be specified as globs to match more than one file at a time. Be sure to wrap the glob in single quotes to ensure that the glob is not resolved by your shell and is passed to Parcel directly. This ensures that Parcel can automatically pick up newly created files matching the glob without needing to restart.

$ parcel './src/*.html'

入口也可以是目录，在这种情况下，必须存在包含 source 字段的 package.json 文件。详情请参阅下文。

¥Entries may also be directories, in which case a package.json file containing a source field must be present. See below for details.

`package.json#source`

package.json 中的 source 字段可以指定一个或多个入口文件。

¥The source field in package.json can specify one or more entry files.

{
  "source": "src/index.html"
}

{
  "source": ["src/a.html", "src/b.html"]
}

`package.json#targets.*.source`

package.json 中声明的任何目标中的 source 字段都可以指定特定于该目标的一个或多个入口文件。例如，你可以同时构建前端和后端，或者桌面和移动应用。有关配置目标的详细信息，请参阅下文。

¥The source field within any target declared in package.json can specify one or more entry files that are specific to that target. For example, you could build your frontend and backend simultaneously, or your desktop and mobile apps. See below for details about configuring targets.

{
  "targets": {
    "frontend": {
      "source": "app/index.html"
    },
    "backend": {
      "source": "api/index.js"
    }
  }
}

目标

¥Targets

Parcel 遵循每个已解析入口中的依赖来为一个或多个目标构建源代码。目标指定输出目录或文件路径，以及有关如何编译代码的信息。

¥Parcel follows the dependencies in each resolved entry to build your source code for one or more targets. Targets specify the output directory or file path, as well as information about how your code should be compiled.

默认情况下，Parcel 包含一个输出到 dist 文件夹的隐式目标。这可以使用 --dist-dir CLI 选项覆盖。

¥By default, Parcel includes a single implicit target which outputs into the dist folder. This can be overridden using the --dist-dir CLI option.

$ parcel build src/index.html --dist-dir output

还可以使用 targets 字段在 package.json 中指定输出目录。这将覆盖 --dist-dir CLI 选项。

¥The output directory can also be specified in package.json using the targets field. This will override the --dist-dir CLI option.

{
  "targets": {
    "default": {
      "distDir": "./output"
    }
  }
}

环境

¥Environments

除了输出位置之外，目标还指定有关代码将运行的“环境”的信息。它们告诉 Parcel 要构建什么类型的环境（例如浏览器或 Node.js），以及你支持的每个引擎的版本。这会影响 Parcel 编译代码的方式，包括要转译的语法。

¥In addition to the output location, targets specify information about the “environment” your code will run in. They tell Parcel what type of environment to build for (e.g. a browser or Node.js), as well as what versions of each engine you support. This influences how Parcel compiles your code, including what syntax to transpile.

`package.json#browserslist`

对于浏览器目标，package.json 中的 browserslist 字段可用于指定你支持的浏览器。你可以按使用情况统计或按特定浏览器的版本范围进行查询。请参阅浏览器列表文档了解更多信息。

¥For browser targets, the browserslist field in package.json can be used to specify which browsers you support. You can query by usage statistics or by version ranges of specific browsers. See the browserslist docs for more information.

{
  "browserslist": "> 0.5%, last 2 versions, not dead"
}

`package.json#engines`

对于 Node.js 和其他目标，package.json 中的 engines 字段可用于指定你支持的版本。引擎是使用 semver 范围指定的。

¥For Node.js and other targets, the engines field in package.json can be used to specify which versions you support. Engines are specified using a semver range.

{
  "engines": {
    "node": ">= 12"
  }
}

隐式环境

¥Implicit environments

当一个文件依赖于另一个文件时，环境将从其父级继承。但你对资源的依赖方式可能会改变环境的某些属性。例如，当依赖于 Service Worker 时，环境会自动更改为 Service Worker 上下文，以便正确编译代码。

¥When one file depends on another, the environment is inherited from its parent. But how you depend on the asset can change some properties of the environment. For example, when depending on a service worker, the environment is automatically changed into a service worker context so that the code is compiled appropriately.

navigator.serviceWorker.register(new URL('service-worker.js', import.meta.url));

差异化打包

¥Differential bundling

“差异打包”是一种为不同目标提供多个版本的代码的想法，并允许浏览器选择最佳版本进行下载。当你在 HTML 文件中使用 <script type="module"> 元素，并且环境指定的某些浏览器本身不支持 ES 模块时，Parcel 也会自动生成 <script nomodule> 后备。

¥“Differential bundling” is the idea of shipping multiple versions of your code for different targets, and allowing the browser to choose the most optimal one to download. When you use a <script type="module"> element in an HTML file, and some of the browsers specified by the environment do not support ES modules natively, Parcel will automatically generate a <script nomodule> fallback as well.

<script type="module" src="app.js"></script>

被编译为：

¥is compiled to:

<script type="module" src="app.c9a6fe.js"></script>
<script nomodule src="app.f7d631.js"></script>

这使得支持 ES 模块的现代浏览器可以下载更小的包，而旧版浏览器仍然可以使用后备支持。通过避免现代 JavaScript 语法（如类、箭头函数、异步/等待等）的转换，可以显着减少包大小并缩短加载时间。

¥This allows modern browsers that support ES modules to download a much smaller bundle, while legacy browsers are still supported using a fallback. This can significantly reduce bundle sizes and improve load times by avoiding transpilation of modern JavaScript syntax like classes, arrow functions, async/await, and more.

这会根据你的浏览器目标自动发生，如 package.json 中 "browserslist" 字段中声明的那样。如果没有声明 browserslist，或者所有浏览器目标都原生支持 ES 模块，则不会生成 nomodule 回退。

¥This happens automatically based on your browser targets, as declared in the "browserslist" field in your package.json. If no browserslist is declared, or all browser targets support ES modules natively, then a nomodule fallback will not be generated.

多个目标

¥Multiple targets

你可能有多个目标，以便同时为多个不同环境构建源代码。例如，你可以为应用设置“现代”和“传统”目标，或者为库设置 ES 模块和 CommonJS 目标 (见下文)。

¥You may have multiple targets in order to build your source code for multiple different environments simultaneously. For example, you could have “modern” and “legacy” targets for an app, or ES module and CommonJS targets for a library (see below).

使用 package.json 中的 targets 字段配置目标。每个目标都有一个名称（指定为 targets 字段下的键）以及关联的配置对象。例如，每个目标中的 engines 字段可用于自定义其编译环境。

¥Targets are configured using the targets field in package.json. Each target has a name, specified as a key under the targets field, and an associated configuration object. For example, the engines field within each target can be used to customize the environment it is compiled for.

{
  "targets": {
    "modern": {
      "engines": {
        "browsers": "Chrome 80"
      }
    },
    "legacy": {
      "engines": {
        "browsers": "> 0.5%, last 2 versions, not dead"
      }
    }
  }
}

当指定多个目标时，输出将默认写入 dist/${targetName}（例如上例中的 dist/modern 和 dist/legacy）。这可以使用每个目标中的 distDir 字段进行自定义。或者，如果目标只有一个入口，则可以使用与目标名称对应的顶层 package.json 字段为输出指定确切的文件名。

¥When multiple targets are specified, the outputs will be written to dist/${targetName} by default (e.g. dist/modern and dist/legacy in the above example). This can be customized using the distDir field in each target. Alternatively, if the target has only a single entry, an exact file name can be specified for the output using a top-level package.json field corresponding to the target name.

{
  "modern": "dist/modern.js",
  "legacy": "dist/legacy.js",
  "targets": {
    "modern": {
      "engines": {
        "browsers": "Chrome 80"
      }
    },
    "legacy": {
      "engines": {
        "browsers": "> 0.5%, last 2 versions, not dead"
      }
    }
  }
}

库目标

¥Library targets

Parcel 包含一些用于构建库的内置目标。其中包括 main、module、browser 和 types 字段。

¥Parcel includes some builtin targets for building libraries. These include the main, module, browser, and types fields.

{
  "name": "my-library",
  "version": "1.0.0",
  "source": "src/index.js",
  "main": "dist/main.js",
  "module": "dist/module.js",
  "types": "dist/types.d.ts"
}

默认情况下，库目标不打包来自 node_modules 的依赖。此外，默认情况下禁用库的缩小。可以使用 targets 字段中的适当选项覆盖这些设置（见下文）。无法对库目标禁用作用域提升。

¥Library targets do not bundle dependencies from node_modules by default. In addition, minification is disabled by default for libraries. These can be overridden using the appropriate option in the targets field (see below). Scope hoisting cannot be disabled for library targets.

库目标根据目标自动输出原生 ES 模块或 CommonJS。

¥Library targets automatically output either native ES modules or CommonJS depending on the target.

main - 默认情况下，输出 CommonJS。如果使用了 .mjs 扩展，或者指定了 "type": "module" 字段，则输出 ES 模块。

¥**main** – by default, outputs CommonJS. If the .mjs extension is used, or the "type": "module" field is specified, then an ES module is output instead.
module - 输出 ES 模块。

¥**module** – outputs an ES module.
browser - 浏览器特定的 main 字段覆盖。输出 CommonJS。

¥**browser** – a browser-specific override of the main field. Outputs CommonJS.

如果还有可用的 browser 目标，或者指定了 engines.node 但未指定浏览器目标，则默认为 Node 环境编译 main 和 module。否则，默认情况下它们会针对浏览器环境进行编译。这可以使用目标配置中的 context 选项覆盖（见下文）。

¥main and module are compiled for a Node environment by default if there is also a browser target available, or if engines.node is specified and no browser targets are specified. Otherwise, they are compiled for a browser environment by default. This can be overridden using the context option in the target config (see below).

要使 Parcel 忽略这些字段之一，请在 targets 字段中指定 false。

¥To make Parcel ignore one of these fields, specify false in the targets field.

{
  "main": "unrelated.js",
  "targets": {
    "main": false
  }
}

有关使用 Parcel 构建库的介绍，请参阅使用 Parcel 构建库。

¥See Building a library with Parcel for an intro to building libraries with Parcel.

目标选项

¥Target options

`context`

'node' | 'browser' | 'web-worker' | 'service-worker' | 'worklet' | 'electron-main' | 'electron-renderer'

context 属性定义要构建的环境类型。这告诉 Parcel 有哪些特定于环境的 API 可用，例如 DOM、Node 文件系统 API 等

¥The context property defines what type of environment to build for. This tells Parcel what environment-specific APIs are available, e.g. the DOM, Node filesystem APIs, etc.

对于内置库目标（例如 main 和 module），会自动推断 context。更多详情请参阅上面的库目标。

¥For builtin library targets (e.g. main and module), the context is automatically inferred. See Library targets above for more details.

`engines`

覆盖该目标的顶层 package.json#engines 和 browserslist 字段中定义的引擎。目标内的 engines.browsers 字段可以像 browserslist 一样使用。有关详细信息，请参阅上面的环境和多个目标。

¥Overrides the engines defined in the top-level package.json#engines and browserslist fields for this target. The engines.browsers field within a target can be used just like browserslist. See Environments and Multiple targets above for more information.

`outputFormat`

'global' | 'esmodule' | 'commonjs'

定义要输出的模块类型。

¥Defines what type of module to output.

global - 可以在浏览器中的 <script> 标记中加载的经典脚本。不支持库目标。

¥global – a classic script that could be loaded in a <script> tag in the browser. Not supported for library targets.
esmodule - 使用 import 和 export 语句的 ES 模块。可以在浏览器中的 <script type="module"> 标签中加载，或者由 Node.js 或其他打包器加载。

¥esmodule – an ES module using import and export statements. Could be loaded in a <script type="module"> tag in the browser, or loaded by Node.js or another bundler.
commonjs - 使用 require 和 module.exports 的 CommonJS 模块。可以由 Node.js 或其他打包器加载。

¥commonjs – a CommonJS module using require and module.exports. Could be loaded by Node.js or another bundler.

对于内置库目标（例如 main 和 module），会自动推断 outputFormat。目标顶层 package.json 字段中定义的文件扩展名也可能会影响输出格式。更多详情请参阅上面的库目标。

¥For builtin library targets (e.g. main and module), the outputFormat is automatically inferred. The file extension defined in the target's top-level package.json field may also influence the output format. See Library targets above for more details.

`scopeHoist`

启用或禁用作用域提升。默认情况下，为生产构建启用作用域提升。--no-scope-hoist CLI 标志可用于在运行 parcel build 时禁用作用域提升。还可以通过在目标配置中设置 scopeHoist 选项来禁用作用域提升。

¥Enables or disables scope hoisting. By default, scope hoisting is enabled for production builds. The --no-scope-hoist CLI flag can be used to disable scope hoisting when running parcel build. Scope hoisting may also be disabled by setting the scopeHoist option in the target config.

`isLibrary`

当设置为 true 时，目标被视为将发布到 npm 并由另一个工具使用的库，而不是直接在浏览器或其他目标环境中使用。当 true 时，outputFormat 选项必须为 esmodule 或 commonjs，并且 scopeHoist 不得设置为 false。

¥When set to true, the target is treated as a library that would be published to npm and consumed by another tool rather than used directly in a browser or other target environment. When true, the outputFormat option must be either esmodule or commonjs and scopeHoist must not be set to false.

对于内置库目标（例如 main 和 module），它会自动设置为 true。更多详情请参阅上面的库目标。

¥For builtin library targets (e.g. main and module), this is automatically set to true. See Library targets above for more details.

`optimize`

启用或禁用优化（例如缩小）。确切的行为由插件决定。默认情况下，在生产构建 (parcel build) 期间启用优化，库目标除外。这可以使用目标配置中的 --no-optimize CLI 标志或 optimize 选项来覆盖。

¥Enables or disables optimization (e.g. minification). Exact behavior is determined by plugins. By default, optimization is enabled during production builds (parcel build), except for library targets. This can be overridden using the --no-optimize CLI flag or the optimize option in the target config.

`includeNodeModules`

确定是打包 node_modules 还是将它们视为外部。对于浏览器目标，默认值为 true；对于库目标，默认值为 false。可能的值为：

¥Determines whether to bundle node_modules or treat them as external. The default is true for browser targets, and false for library targets. Possible values are:

false - node_modules 中不包含任何文件。

¥**false** – does not include any files in node_modules.
数组 – 要包含的包名称列表。在以下示例中，仅打包 react。node_modules 中的所有其他文件均被排除。

¥an array – a list of packages names to include. In the following example, only react is bundled. All other files in node_modules are excluded.
```
{
  "targets": {
    "main": {
      "includeNodeModules": ["react"]
    }
  }
}
```
一个对象 - 包名称到布尔值的映射。如果未列出某个包，则将其包含在内。在下面的示例中，除了 React 之外的所有 node_modules 都被打包。

¥an object – a mapping of package names to booleans. If a package is not listed, it is included. In the following example, all node_modules except react are bundled.
```
{
  "targets": {
    "main": {
      "includeNodeModules": {
        "react": false
      }
    }
  }
}
```

`sourceMap`

启用或禁用源映射，并设置源映射选项。默认情况下，源映射处于启用状态。可以使用 --no-source-maps CLI 标志或通过将目标配置中的 sourceMap 选项设置为 false 来覆盖此设置。

¥Enables or disables source maps, and sets source map options. By default, source maps are enabled. This can be overridden using the --no-source-maps CLI flag, or by setting the sourceMap option in the target config to false.

sourceMap 选项还接受具有以下选项的对象。

¥The sourceMap option also accepts an object with the following options.

inline - 是否将源映射作为数据 URL 内联到包中，而不是作为单独的输出文件链接到它。

¥inline – Whether to inline the source map as a data URL into the bundle rather than link to it as a separate output file.
inlineSources - 是否将原始源代码内联到源映射中而不是从 sourceRoot。在构建生产浏览器目标时，默认设置为 true。

¥inlineSources – Whether to inline the original source code into the source map rather than load them from the sourceRoot. This is set to true by default when building browser targets for production.
sourceRoot - 加载原始源代码的 URL。当使用内置的 Parcel 开发服务器时，这是在开发过程中自动设置的。否则，它默认为从项目根到包的相对路径。

¥sourceRoot – The URL at which to load the original source code. This is set automatically in development when using the builtin Parcel dev server. Otherwise, it defaults to a relative path to the bundle from the project root.

`source`

覆盖目标的 package.json 中的顶层 source 字段。这允许每个目标有不同的入口。详细信息请参见 package.json#targets.*.source。

¥Overrides the top-level source field in package.json for a target. This allows for each target to have different entries. See package.json#targets.*.source for more details.

`distDir`

设置此目标中编译包的写入位置。默认情况下，如果仅给出一个目标，则为 dist；对于多个目标，则为 dist/${targetName}。详细信息请参见目标。

¥Sets the location where compiled bundles in this target will be written. By default, this is dist if only a single target is given, or dist/${targetName} for multiple targets. See Targets for more details.

`publicUrl`

设置运行时加载该包的基本 URL。将自动附加来自 distDir 的打包包的相对路径。如果打包包是从与你的网站相同的域加载的，则 publicUrl 可以是完全限定的 URL（例如 https://some-cdn.com/）或绝对路径（例如 /public）。

¥Sets the base URL at which this bundle will be loaded at runtime. The bundle's relative path from the distDir will be automatically appended. publicUrl can be either a fully qualified URL (e.g. https://some-cdn.com/ or an absolute path (e.g. /public) if bundles are loaded from the same domain as your website.

默认情况下，publicUrl 是 /。如果你的 HTML 文件和其他资源部署到同一位置，这是一个很好的默认值。如果你将资源部署到其他位置，你可能需要设置 publicUrl。还可以使用 --public-url CLI 选项设置公共 URL。

¥By default the publicUrl is /. This is a good default if your HTML files and other assets are deployed to the same location. If you deploy assets to a different location, you'll likely need to set publicUrl. The public URL can also be set using the --public-url CLI option.

在大多数情况下，使用从父包到子包的相对路径来加载包。这允许将部署移动到新位置而无需重新构建（例如，将暂存构建提升到生产）。当相对路径不可能时（例如在 HTML 中），使用 publicUrl。

¥In most cases, bundles are loaded using a relative path from the parent bundle to the child bundle. This allows the deployment to be moved to a new location without re-building (e.g. promoting a staging build to production). The publicUrl is used when relative paths are not possible (e.g. in HTML).