# @atlassian/webresource-webpack-plugin 中文文档

规范地址：https://npmcn.com/package/%40atlassian/webresource-webpack-plugin/

版本：7\.2\.2
npm 元数据更新时间：2026-10-23T08:53:18.124Z
中文译文更新时间：2026-11-07T03:18:30.644Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlassian/webresource-webpack-plugin
原文对照：https://npmcn.com/package/%40atlassian/webresource-webpack-plugin/?lang=original
项目主页：https://bitbucket.org/atlassianlabs/fe-server
源码仓库：https://bitbucket.org/atlassianlabs/fe-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：244 kB，88 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=12
- 运行依赖：5 个
- 首次发布：2025-05-29T09:23:15.032Z
- 最新版本发布：2026-10-23T08:53:17.901Z
- 近 30 天下载量：3764（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 19 个）

## 中文简介

从您的网络包装代码自动生成网络资源定义, 用于Atlassian产品或插件.

## 安装

```sh
npm install @atlassian/webresource-webpack-plugin
```

也可以使用：`pnpm add @atlassian/webresource-webpack-plugin`、`yarn add @atlassian/webresource-webpack-plugin`、`bun add @atlassian/webresource-webpack-plugin`

## README

> **_注:_** [@atlassian/webresources-webpack-plugin (中文(简体) )](https://www.npmjs.com/package/@atlassian/webresource-webpack-plugin) 替换旧的 [地图集-网络包装-网络资源-插图](https://www.npmjs.com/package/atlassian-webresource-webpack-plugin) 软件包,现在已贬值.

# 阿特拉斯网络资源网络包插件

![node](https://img.shields.io/badge/node-18%2B-blue.svg) ![npm](https://img.shields.io/badge/npm-6.14%2B-blue.svg) ![webpack](https://img.shields.io/badge/webpack-5%2B-blue.svg)

从您的网络包装代码自动生成网络资源定义, 以供使用 在Atlassian产品或插件中.

## 为什么?

[Atlassian P2 插件系统](https://bitbucket.org/atlassian/atlassian-plugins) 2008年运出. 当时,扶养管理 p2系统 [网络资源管理器,或 WRM](https://bitbucket.org/atlassian/atlassian-plugins-webresource) -是管理成长的神的终点 前端资源的复杂性。 它除其他外提出:

-   指定相关资源捆绑的能力,称为"网络资源".
-   确定网络资源相互依存性的能力,以便
-   在生产过程中可实现对必要编码的剪接,以及
-   可以维持源顺序.

快进至2017年,前端开发与当时大相径庭. JavaScript 模块系统和 Webpack 解决了WRM最初设定的许多问题 出来.

不幸的是,Atlassian的插件系统不会说网页包. 幸好我们可以教书 (原始内容存档于2018-10-21). Webpack to speak Atlassian-Plugin. 这个插件就是这样做的.

## 这有什么用?

当您将这个插件添加到您的 Webpack 配置时, 它会生成 XML 文件 和各种WRM配置 使您的代码运行在Atlassian产品.

您可以使用任何 JavaScript 模块系统来写入您的插件的前端代码 . 此插件将想方设法将全部内容都转换为正确 `<web-resource>` 声明, 与适当 `<dependency>` 声明使您的代码最终加载 在产品运行时间的正确顺序.

此插件支持并生成以下 Webpack 行为的正确WRM输出 :

-   (单位:千美元) `<web-resource>` 每个网页包装入口
-   对 `<web-resource>`s 用于代码分割/ 装入同步块
-   装入非JavaScript资源(通过 `ExtractTextPlugin` (见a/cn.9/wg.iii/wp.83,第6段).

## 如何使用插件

### 基本设置

将此插件添加到您的网络包配置 。 每个入口的网络包装, 适当 `<web-resource>` 定义将在 XML 文件中为您生成, 然后可以捆绑到您的 Atlassian 产品或插件中, 准备服务 到产品运行时间的浏览器.

考虑到这个网络包配置:

```js
const WrmPlugin = require('@atlassian/webresource-webpack-plugin');

module.exports = {
  entry: {
    'my-feature': path.join(FRONTEND_SRC_DIR, 'simple.js'),
  },
  plugins: [
    new WrmPlugin({
      pluginKey: 'my.full.plugin.artifact-id',
      contextMap: {
        'my-feature': ['atl.general'],
      },
      xmlDescriptors: path.resolve(OUTPUT_DIR, 'META-INF', 'plugin-descriptors', 'wr-defs.xml'),
    }),
  ],
  output: {
    filename: 'bundled.[name].js',
    path: path.resolve(OUTPUT_DIR),
  },
};
```

输出会去 `<OUTPUT_DIR>/META-INF/plugin-descriptors/wr-defs.xml`,看起来是这样的:

```xml
<bundles>

        <web-resource key="entrypoint-my-feature">
            <transformation extension="js">
                <transformer key="jsI18n"/>
            </transformation>
            <context>atl.general</context>
            <resource name="bundled.my-feature.js" type="download" location="bundled.my-feature.js" />
        </web-resource>

</bundles>
```

还有.., `<OUTPUT_DIR>/META-INF/fe-manifest-associations/` 将包含此 webpack 构建创建的资源列表 以及AMPs资源协会功能的国家预防机制软件包名称.

软件包名称可以通过通过指定 `packageName` 字段直接取入WrmPlugin,否则取出 自动从 Webpack 最近的父软件包.json `context` 目录.

关联在 P2 插件中被 AMP 自动检测出, 并预计将在 `target/classes/META-INF/fe-manifest-associations` 用于构建插件.

#### 在您的 P2 插件中完成输出

在您的 P2 插件工程中 `pom.xml` 文件,添加 `META-INF/plugin-descriptors` 目录作为一个 `<Atlassian-Scan-Folders>` 标签 输入 `<instruction>` 用于 AMPS 插件的构建配置.

```xml
<build>
  <plugins>
    <plugin>
      <!-- START of a bunch of stuff that is probably different for your plugin, but is outside
           the scope of this demonstration -->
      <groupId>com.atlassian.maven.plugins</groupId>
      <artifactId>maven-amps-plugin</artifactId>
      <version>6.2.11</version>
      <!-- END differences with your plugin -->
      <configuration>
        <instructions>
          <Atlassian-Scan-Folders>META-INF/plugin-descriptors</Atlassian-Scan-Folders>
        </instructions>
      </configuration>
    </plugin>
  </plugins>
</build>
```

### 演示 P2 插件用途

您可以在此看到使用 Webpack 插件的演示 P2 插件 : [{\\fn华文楷体\\fs20\\bord1\\shad1\\1che0e0e0\\2ch000000}相克出道出道了到底出道了](https://bitbucket.org/serverecosystem/sao4fed-bundle-the-ui)

-   观看这个 AtlasCamp 2018 的谈话, 使用这个插件等使您的 devloop 超快: [https://youtu.be/ VamdjcJCc0Y (中文(简体) )](https://youtu.be/VamdjcJCc0Y)
-   观看此 AtlasCamp 2017 讨论如何在 P2 顶上构建和整合您自己的前端编程, 它引入了此插件的α版本 : [https://youtu.be/2yf-TzKerVQ?t=537 (英语)](https://youtu.be/2yf-TzKerVQ?t=537)

## 特征

### 代码分割

如果你使用任何网络包装的代码分割技术,例如调用 `require.ensure`, (中文(简体) ), 此插件将自动生成 `<web-resource>` 定义,以及 自动将其翻译为适当的呼叫,以便在Atlassian同步加载 产品运行时间.

换句话说,你实际上没有努力 使你的关键路径小:

### 灵活生成 `web-resource` 定义

默认情况下,生成的网络资源将具有:

-   基于您网络包装条目名称的密钥,以及
-   将列入 `<context>` 以输入点命名.

例如,一个被命名为"我的地物"的入口将产生这样的网络资源:

```xml
<web-resource key="entrypoint-my-feature">
  <context>my-feature</context>
  <!-- the resources for your entry-point -->
</web-resource>
```

对于新代码,这应该足够让你的特性加载到你想要的位置 插件或产品 - 假设服务器端的调用包含您的网络资源 .

有时,为了确保你的代码负载 当它被预期,你需要 覆盖 为您生成的值。 在定义 `WrmPlugin`配置,可以提供:

-   A 类 `webresourceKeyMap` 将网络资源的密钥或名称更改为您需要的,或者
-   A 类 `contextMap` 将网络资源包含在您期望它加载的任意数量的网络资源上.

很可能你想要为一个网络资源指定额外的上下文来加载到. 何时 您所有的网络资源都是通过上下文自动生成和加载的,不需要知道它的密钥. 你个 通常会在将旧代码重构到网络包装时提供自己的网页资源密钥,以保留 任何先前存在的代码中的依赖关系.

### 模块映射到 `web-resource`编号

如果使用普通库或模块——例如:"jquery"或"backbone"——你知道 此模块由产品运行时的 P2 插件提供, 您可以绘制您的用法 模块 `web-resource` 这提供了它.

你只需要宣布适当的网页包装 `external` 模块,并添加条目 用于外部 `providedDependencies` 此插件的配置 。 当你的代码是 编译,此插件将自动添加一个合适的 `web-resource` 依赖关系 将保证您的代码负载在它的受抚养人之后, 并会防止您的捆绑变得太大.

详细情况请检查 `providedDependencies` 区域.

### 遗产 `web-resource` 包含

90%的时间, 您的 JavaScript 代码应该声明对其它模块的明确依赖 . 在剩下的10%的情况下,您可能需要在运行时依赖WRM,以确保您的代码负载进入 正确的顺序。 9%的时间,模块映射功能 应该足够你。 其余部分 1%,你可能只需要添加一个 `web-resource` 依赖强制命令.

您可以在代码中添加导入语句,以添加一个 `<dependency>` 到您生成的网络资源 .

包括 `web-resource`s 从导出 _这个_ 插件, 您可以使用短标记, 如 :

```js
// in AMD syntax
define(function (require) {
  require('wr-dependency!my-webresource');
  console.log('my-webresource will have been loaded synchronously with the page');
});

// in ES6
import 'wr-dependency!my-webresource';

console.log('my-webresource will have been loaded synchronously with the page');
```

包括出口资源 _其他项目_ 插件, 提供完整的插件密钥 :

```js
// in AMD syntax
define(function (require) {
  require('wr-dependency!com.atlassian.auiplugin:dialog2');
  console.log('webresource will have been loaded synchronously with the page');
});

// in ES6 syntax
import 'wr-dependency!com.atlassian.auiplugin:dialog2';

console.log('webresource will have been loaded synchronously with the page');
```

### 遗产运行时间 `resource` 包含

95%的时间, 您应用程序的非 JavaScript 资源-- CSS, 图像, 模板等.. 可以通过网包装入器捆绑和装入。 有时候,虽然,你会有 只在Atlassian产品运行期间工作的资源 -- -- 认为事情是这样的 阿特拉斯语 豆类模板和产品 Less文件 用于外观和外观样式——和 无法在超前编译期间 让他们工作.

在这种情况下,您可以在代码中添加导入语句,以添加一个 `<resource>` 给您的 生成的网络资源 :

```js
// in AMD syntax
define(function (require) {
  require('wr-resource!my-runtime-styles.css!path/to/the/styles.less');
  require('wr-resource!my-compiled-templates.js!path/to/the/templates.soy');

  console.log('these styles and templates will be transformed to CSS and JS at product runtime.');
});

// in ES6 syntax
import 'wr-resource!my-runtime-styles.css!path/to/the/styles.less';
import 'wr-resource!my-compiled-templates.js!path/to/the/templates.soy';

console.log('these styles and templates will be transformed to CSS and JS at product runtime.');
```

## 配置插件

Atlassian Web-Resource网络包插件具有一些配置选项.

### `pluginKey` (须)

您的 P2 插件的完全合格组名和 artechId 。 由于WRM的工作方式,这个 值对于支持同步块的装入以及任意性 (非JavaScript)资源.

### `xmlDescriptors` (须)

一个绝对文件路径, 输出生成的 XML 到哪里 。 这应该是指子目录 马文项目 `${project.build.outputDirectory}` (评价为: `target/classes` 在一个 标准马文项目).

此配置值的子目录部分需要在工程中配置 `pom.xml`,作为 以上基本使用部分所示.

### `addEntrypointNameAsContext` (备选)

默认是 `false`。 。 。 .

设定为 `true`,所有生成的网络资源都将添加到 a 上下文与出入口同名.

切入点名称中任何打破批次 URL 的字符都被替换为 `-`,以及任何线索 `-` 已删除 : 切入点 `feature/nested/app` 成为上下文 `feature-nested-app`。使用“contextMap”选项手动设置名称.

### `addAsyncNameAsContext` (备选)

默认是 `false`。 。 。 .

设定为 `true`,所有生成的用于有名称(通过 `webpackChunkName` 将添加到 名称“ async- chunk- ” 的上下文, 字符替换相同 作为 `addEntrypointNameAsContext`。 。 。 .

### `contextMap` (备选)

一组键值对,允许您指定哪些网络包条目点 应在Atlassian产品运行时间的网络资源背景下出现.

您可以提供单个的网络资源上下文作为字符串,也可以提供一系列上下文字符串.

这些名称作为书面使用, 所以一个打破批量 URL 失败构建的名称: 上下文可能不包含 `/`, (中文(简体) ), `?`, (中文(简体) ), `+`, (中文(简体) ), `,`, (中文(简体) ), `#`, (中文(简体) ), `%`, (中文(简体) ), `&`,白色空间或可打印的 ASCII 外部的任何东西,并且可能不会从 `-`。价值 不是一个非空字符串被忽略.

### `conditionMap` (备选)

指定对某一入境点适用何种条件的对象. 简单示例 :

```json
conditionMap: {
  "my-first-entry-point": {
    "class": "foo.bar"
  },
}
```

将产生 :

```xml
<condition class="foo.bar" />
```

配有参数的复杂嵌入实例:

```json
conditionMap: {
  "my-first-entry-point": {
    "type": "AND",
    "conditions": [
      {
        "type": "OR",
        "conditions": [
          {
            "class": "foo.bar.baz",
            "invert": true,
            "params": [
              {
                "attributes": {
                  "name": "permission"
                },
                "value": "admin"
              }
            ]
          },
          {
            "class": "foo.bar.baz2",
            "params": [
              {
                "attributes": {
                  "name": "permission"
                },
                "value": "project"
              }
            ]
          }
        ]
      },
      {
        "class": "foo.bar.baz3",
        "params": [
          {
            "attributes": {
              "name": "permission"
            },
            "value": "admin"
          }
        ]
      }
    ]
  }
}
```

将产生 :

```xml
<conditions type="AND">
  <conditions type="OR">
    <condition class="foo.bar.baz" invert="true">
      <param name="permission">admin</param>
    </condition>
    <condition class="foo.bar.baz2" >
      <param name="permission">project</param>
    </condition>
  </conditions>
  <condition class="foo.bar.baz3" >
    <param name="permission">admin</param>
  </condition>
</conditions>
```

### `dataProvidersMap` (备选)

这个 `dataProvidersMap` 选项允许在输入点和数据提供者列表之间配置关联.

数据提供者可用于提供从服务器端到前端的数据,并声称使用 `WRM.data.claim` API (英语). 欲了解更多数据提供者,请参考: [正式文件](https://developer.atlassian.com/server/framework/atlassian-sdk/adding-data-providers-to-your-plugin/)。 。 。 .

要将条目与数据提供者列表相连接,您可以配置以下的 Webpack 配置 :

```js
module.exports = {
  entrypoints: {
    'my-first-entry-point': './first-entry-point.js',
    'my-second-entry-point': './first-entry-point.js',
  },

  plugins: [
    WrmPlugin({
      pluginKey: 'my.full.plugin.artifact-id',
      dataProvidersMap: {
        'my-first-entry-point': [
          {
            key: 'my-foo-data-provider',
            class: 'com.example.myplugin.FooDataProvider',
          },
        ],

        'my-second-entry-point': [
          {
            key: 'my-bar-data-provider',
            class: 'com.example.myplugin.BarDataProvider',
          },

          {
            key: 'my-bizbaz-data-provider',
            class: 'com.example.myplugin.BizBazDataProvider',
          },
        ],
      },
    }),
  ],
};
```

将产生 :

```xml
<atlassian-plugin>
    <web-resource key="<<key-of-my-first-entry-point>>">
        <resource  />
        <resource  />

        <data key="my-foo-data-provider" class="com.example.myplugin.FooDataProvider" />
    </web-resource>

    <web-resource key="<<key-of-my-first-entry-point>>">
        <resource  />
        <resource  />

        <data key="my-bar-data-provider" class="com.example.myplugin.BarDataProvider" />
        <data key="my-bizbaz-data-provider" class="com.example.myplugin.BizBazDataProvider" />
    </web-resource>
</atlassian-plugin>
```

### `deprecatedEntrypoints` (备选)

指定哪些切入点应标为已贬值的对象.

A 类 `true` 可使用数值来简单地标出一个切入点被贬值,而不提供任何补充资料.

否则,可以使用一个对象来提供附加上下文,说明何时和为什么切入点贬值。 给 `alternative` 键, 数值应当为: `plugin-key:web-resource`,或者作为同一插件中另一个切入点的参考.

```js
module.exports = {
  entrypoints: {
    'my-first-entry-point': './first-entry-point.js',
    'my-second-entry-point': './second-entry-point.js',
    'my-third-entry-point': './third-entry-point.js',
  },

  plugins: [
    WrmPlugin({
      pluginKey: 'my.full.plugin.artifact-id',
      deprecatedEntrypoints: {
        'my-first-entry-point': true,
        'my-second-entry-point': {
          sinceVersion: '3.0',
          removeInVersion: '4.0',
          // alternative could also reference another entrypoint i.e. 'my-third-entry-point'
          alternative: 'some.other.plugin:replacement-resource',
          extraInfo: 'We moved all functionality to some.other.plugin',
        },
      },
    }),
  ],
};
```

将产生 :

```xml
<atlassian-plugin>
    <web-resource key="entrypoint-my-first-entry-point">
        <!-- ... rest of definition ... -->
        <deprecated />
    </web-resource>
    <web-resource key="entrypoint-my-second-entry-point">
        <!-- ... rest of definition ... -->
        <deprecated since="3.0"
                    remove="4.0"
                    alternative="some.other.plugin:replacement-resource"
        >
            We moved all functionality to some.other.plugin
        </deprecated>
    </web-resource>
</atlassian-plugin>
```

### `transformationMap` (备选)

指定要应用到文件类型的对象. 默认转换为:

-   `*.js` 备忘 `jsI18n`
-   `*.soy` 备忘 `soyTransformer`, (中文(简体) ), `jsI18n`

自定义转换的示例配置 :

```json
{
  "transformationMap": {
    "js": ["myOwnJsTransformer"],
    "sass": ["myOwnSassTransformer"]
  }
}
```

这将为每个生成的网络资源设定以下转型:

```xml
<web-resource key="...">
    <transformation extension="js">
      <transformer key="myOwnJsTransformer"/>
    </transformation>
    <transformation extension="sass">
      <transformer key="myOwnSassTransformer"/>
    </transformation>
</web-resource>
```

如果您想要延长默认变换, 您可以使用内置 `extendTransformations` 函数由插件提供. 它会将默认的转换与您的自定义配置合并 :

```js
const WrmPlugin = require('@atlassian/webresource-webpack-plugin');

new WrmPlugin({
  pluginKey: 'my.full.plugin.artifact-id',
  transformationMap: WrmPlugin.extendTransformations({
    js: ['myOwnJsTransformer'],
    sass: ['myOwnSassTransformer'],
  }),
});
```

您也可以通过路过完全禁用转换 `false` 插件配置值 :

```json
{
  "transformationMap": false
}
```

### `webresourceKeyMap` (备选)

允许您更改给定的 Web 包条目点生成的 Web 资源的名称 .

当您期望其他插件需要直接依赖您自动生成的网络资源时, 这样做是有用的, 例如 当您重构一个通过 web 软件包生成的已有特性( 及其网络资源) 时.

此参数可以选择 `string` 或者说 `object` 有属性 `key`, (中文(简体) ), `name` 财务报告和审定财务报表 `state` 对应 `key`, (中文(简体) ), `name` 财务报告和审定财务报表 `state` 属性 `web-resource` XML 元素 . `name` 财务报告和审定财务报表 `state` 属性是可选的.

绘图如下:

```json
{
  "webresourceKeyMap": {
    "firstWebResource": "first-web-resource",
    "secondWebResource": {
      "key": "second-web-resource",
      "name": "Second WebResource",
      "state": "disabled"
    }
  }
}
```

将产生下列网络资源:

```xml
<atlassian-plugin>
<web-resource key="first-web-resource" name="" state="enabled">
  <!-- your resources definitions -->
</web-resource>
<web-resource key="second-web-resource" name="Second WebResource" state="disabled">
  <!-- your resources definitions -->
</web-resource>
</atlassian-plugin>
```

### `providedDependencies` (备选)

一个对象的地图,让你联想到什么网络资源 包含特定的外部JS依赖.

外部依赖性绘图的格式如下:

```json5
{
  'dependency-name': {
    dependency: 'atlassian.plugin.key:webresource-key',
    import: {
      // externals configuration
    },
  },
}
```

当您的代码通过网络包编译时, 任意发生 `dependency-name` 在模块导入中找到 语句将在 web 软件包输出中替换,并使用适当的网页资源 `<dependency>` 将会是 添加到生成的网络资源中 .

这个 `import` 属性是一个字符串或对象,指定如何在代码中导入依赖.

提供的对象是紧随 [网络包外部格式](https://webpack.js.org/configuration/externals/#object)。 。 。 .

如果你没有设置 `externalsType` 或者说 `library.type` 在配置中,然后使用的默认属性是 `var`。另一个流行的选择是 `amd` 由于大多数Atlassian产品都使用AMD来装入模块(但随后是 `externalsType` 也应予以确定).

### `wrmManifestPath` (备选)

用于存储对象映射的 WRM 显示文件的路径 . 在 `providedDependencies` 属性是一个依赖性的地图,包括生成的网络资源密钥. 此映射是完全相同的格式 `providedDependencies` 以上选项, 因此,人们可以用这张地图作为源 `providedDependencies` 在另一个建筑中:

```json
{
  "providedDependencies": {
    "dependency-name": {
      "dependency": "atlassian.plugin.key:webresource-key",
      "import": {
        "var": "require('dependency-amd-module-name')",
        "amd": "dependency-amd-module-name"
      }
    }
  }
}
```

#### 说明和限制

-   两者 `output.library` 财务报告和审定财务报表 `output.libraryTarget` 必须设置用于创建 WRM 显示文件.
-   `output.library` 不得含有\[通 或\[通 ,但允许使用\[名\]
-   `output.libraryTarget` 必须设置为 `amd`
-   未来 WRM 清单文件中可能添加更多属性

#### 示例配置

```json
{
  "output": {
    "library": "[name]",
    "libraryTarget": "amd"
  }
}
```

### `resourceParamMap` (备选)

指定额外参数的对象( E)`<param/>`用于 `resource`编号.

例如,要指定内容类型,服务器应该对某一资产文件类型(例如图像/字体)作出回应:

```json
{
  "resourceParamMap": {
    "svg": [
      {
        "name": "content-type",
        "value": "image/svg+xml"
      }
    ]
  }
}
```

某些Atlassian产品可能需要根据装入的文件类型设置具体内容类型. _默认情况下包含 svg 作为“ 图像/ svg+xml” 的内容类型_

### `locationPrefix` (备选)

添加给前缀值到 `location` 属性 `resource` 节点. 当您的 Webpack 输出被放置在插件最终根文件夹的子目录中时使用此选项 .

### `devAssetsHash` (备选)

用户在网络资源名称中提供了包含开发模式所需要全部资产的值(而不是DEV PSEUDO HASH).

### `watch` 财务报告和审定财务报表 `watchPrepare` (备选)

激活"监视-模式". 这必须与一个webpack-dev-server同时运行.

#### `watchPrepare`

在 XML 描述符中创建"代理"资源并引用它们. 这些代理资源将重定向到一个也必须运行的webpack-dev-server. 为使这项工作正常进行,确保webpack-配置"options.output.publicPath"指向webpack-dev-server - 包括其端口. (例如:http://localhost:9000)

#### `watch` (备选)

使用 Webpack-dev-server 运行进程时使用.

### `useDocumentWriteInWatchMode` (备选)

设定为 `true`,生成的监视模式模块将同步将脚本标记添加到文档中 `document.write` 当文档正在装入时,而不是总是依赖同步附加的脚本标记(默认行为).

当捆绑有望提前在页面上提供时,例如当模板中的代码依赖于javascript来被屏蔽地加载时,此功能是有用的.

### `noWRM` (备选)

将不会在 Webpack 运行时间中添加任何 WRM 特性, 或尝试在仍然处理请求时重定向 async- chunk 请求到 `wr-dependency` 财务报告和审定财务报表 `wr-resource`。 。 。 . 这对于在提供WRM功能的运行中产品之外开发前端可能有用.

### `singleRuntimeWebResourceKey` (备选)

使用 Webpack 选项时为 Webpack 运行时间设置一个特定的 Web 资源密钥 `optimization.runtimeChunk` 改为 `single` (见 [运行时间Chunk 文档](https://webpack.js.org/configuration/optimization/#optimizationruntimechunk)) (中文(简体) ). 默认是 `common-runtime`。 。 。 .

### `chunkLoadingGlobal` (备选)

覆盖用于 `output.chunkLoadingGlobal` 当插件自动设置时。 在Webpack 5和Rspack中, `chunkLoadingGlobal` 是用于装入块的全局变量。 何时 **多个应用程序** 在同一个页面上使用此插件负载,每个应用程序必须有一个不同的 `chunkLoadingGlobal` 因此块/模块ID不相冲突。 如果您没有设置 `output.chunkLoadingGlobal` 在您的配置中,插件从 `pluginKey` (或如果提供的话,来自本选项). 如果你已经设置 `output.chunkLoadingGlobal` 在您的 webpack/ rspack 配置中,该值保持不变.

### `verbose` (备选)

显示日志输出的动词。 默认是 `false`。 。 。 .

## 最低要求

此插件的构建是为了与以下版本的外部构建工具相配合:

-   节点 18 (在 P2 插件构建时)
-   [阿特拉斯马文插件套件(AMPS)](https://developer.atlassian.com/server/framework/atlassian-sdk/working-with-maven/#using-the-amps-maven-plugin-directly) 6.2.11+ (中文(简体) )
-   [阿特拉斯斯网络资源管理器(WRM)](https://bitbucket.org/atlassian/atlassian-plugins-webresource) 4.3.6+ (单位:千美元)

这个插件通过webpack 5.0+和rspack 1.5+测试.

### 建议使用网页包5

-   要编译 CSS, 使用 `css-loader >= 5` 和 `mini-css-extract-plugin >= 2`。 。 。 .
-   使用时 `mini-css-extract-plugin` 运行时间选项需要设置为错误 。 这样可以防止 `mini-css-extract-plugin` 由WRM完成.

## 升级指南

-   [升级到7.0.0](https://bitbucket.org/atlassianlabs/fe-server/src/master/packages/webresource-webpack-plugin/UPGRADE_700.md)

## 解决问题和已知问题

### 自动排除出故障的工具

我们提供了一个工具,帮助排除网络包和Atlassian P2项目的配置出问题.

要检查您的工程是否正确配置, 请打开终端并导航到您的工程的根目录 。 下, 运行故障排除命令 :

```shell
npx @atlassian/wrm-troubleshooting
```

该工具会问你几个问题, 并指引您是否发现您的项目配置有问题 .

你可以读到更多关于 清除故障的工具 [国家预防机制网页 `@atlassian/wrm-troubleshooting` 软件包](https://www.npmjs.com/package/@atlassian/wrm-troubleshooting)。 。 。 .

### 运行时间问题

```
e.O is not a function
```

OR( 当最小化: 虚假)

```
__webpack_require__.O is not a function
```

如果您使用外部插件提供的捆绑的网络资源 `optimization.runtimeChunk: 'single'` 财务报告和审定财务报表 `optimization.splitChunks.chunks: 'all'` 您可能需要配置您的插件来同时使用 `runtime: 'single'` 这样,在加载块时共享的 webpack 运行时对象具有相同的签名.

### 一个页面上的多应用程序(chunk/模块ID冲突)

当使用此插件构建的多个应用程序被加载在同一页上(例如不同的P2插件或出入口)时,每个应用程序的运行时间必须被隔离. 否则,它们可以共享相同的块负载全局和数字块/模块ID可以指每个app中不同的代码.

**解决方案 :** 每个建筑必须有一个独特的 **`output.chunkLoadingGlobal`** (Webpack 5 / Rspack) (中文(简体) ). 插件为您这样做: 如果 `output.chunkLoadingGlobal` 不是在您的配置中设定的 而是从您的配置中设定的 `pluginKey` (因此每个插件都得到一个独特的运行时间). 您可以用插件选项覆盖生成的值 **`chunkLoadingGlobal`**,或设置 **`output.chunkLoadingGlobal`** 直接在您的 Webpack/ rspack 配置中 。 每个应用程序使用不同的配置时不需要额外的每个应用程序配置 `pluginKey`。 。 。 .

### 其他问题

请检查您的构建和捆绑是否如您预期的那样有效, 没有启用此插件 。 您可以禁用WRM Webpack插件,并捆绑代码,以验证webpack输出中没有出错或警告.

这个插件对Webpack最终输出的修改很少. 如果你的包有内容错误, 这可能是由于网页包与您构建配置中的加载器插件的版本不兼容.

此插件的已知问题列表于 [阿特拉斯生态系统问题跟踪仪](https://ecosystem.atlassian.net/jira/software/c/projects/SPFE/issues/)。 。 。 . 我们的发展团队每月审查所有未决问题和分类.

## 常见问题

### @atlassian/webresource-webpack-plugin 是什么？

从您的网络包装代码自动生成网络资源定义, 用于Atlassian产品或插件\.

### 如何安装 @atlassian/webresource-webpack-plugin？

在项目目录运行 npm install @atlassian/webresource-webpack-plugin，或使用 pnpm add / yarn add / bun add。

### @atlassian/webresource-webpack-plugin 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atlassian/webresource-webpack-plugin 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @atlassian/webresource-webpack-plugin 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @atlassian/webresource-webpack-plugin 可以商用吗？

@atlassian/webresource-webpack-plugin 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlassian/webresource-webpack-plugin 的下载量有多少？

根据 npm 官方下载统计，@atlassian/webresource-webpack-plugin 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,764 次，日均约 125 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @atlassian/webresource-webpack-plugin 还在维护吗？

最新版本 7\.2\.2 发布于 2026/10/23（15 天前）；至今共发布 32 个版本，其中过去 12 个月发布了 19 个；首次发布于 2025/05/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。