Elementor GenerateWordPressAssetFileWebpackPlugin 全解析:为 WordPress 自动生成 `.asset.php` 脚本依赖清单
Elementor GenerateWordPressAssetFileWebpackPlugin 全解析:为 WordPress 自动生成 .asset.php 脚本依赖清单
Elementor 在前端工程化中维护了一个专有的 Webpack 插件 @elementor/generate-wordpress-asset-file-webpack-plugin,它在构建阶段为每个 JS 入口自动生成 WordPress 风格(wp_register_script 兼容)的 .asset.php 依赖清单文件,从而把「JS 模块依赖」与「WP 脚本 handle 依赖」在构建期自动打通。本文以该插件包的 CHANGELOG.md 为主线,结合仓库内 plugin.ts、utils.ts、types.ts 及 集成测试,从实现原理、配置项、输出格式到版本演进逐层拆解,读完你可以直接在自己的 WP 主题/插件工程中复刻这套「构建期自动生成依赖清单」的流水线。
一、插件定位:把 Webpack 模块依赖翻译成 WordPress 脚本依赖
在 WordPress 生态中,注册前端脚本的标准做法是调用 wp_register_script( $handle, $src, $deps, $ver ),其中第三个参数 $deps 是「该脚本依赖的其他已注册脚本的 handle 数组」。当项目使用 Webpack 构建、并从 npm 包引入 @wordpress/element、react 等共享库时,$deps 往往需要手工维护,极易与构建产物脱节。
这个插件解决的核心问题正是:让 Webpack 在打包时自动分析每个 entry chunk 的模块依赖,并把它们翻译成对应的 WP 脚本 handle,输出一个 .asset.php 文件。该文件返回形如:
return [
'handle' => 'elementor-v2-app',
'deps' => [
'elementor-v2-editor',
'react',
'react-dom',
'wp-element',
],
];
的结构,PHP 侧拿到 deps 数组后即可直接喂给 wp_register_script,从而消灭手工维护依赖列表的环节。
需要特别说明的是:该插件包的 README.md 带有醒目的警告——当前版本仍在开发中,不建议用于生产环境。因此本文所有内容面向技术学习与二次开发,接入自有项目前请自行评估稳定性。
二、工作原理:一次 processAssets 钩子里的依赖提取
插件的核心实现在 plugin.ts,源码注释表明它受 WordPress 官方 @wordpress/dependency-extraction-webpack-plugin 启发。整体流程可以归纳为四条链路:
1. 挂载时机:thisCompilation + processAssets
apply( compiler: Compiler ) {
compiler.hooks.thisCompilation.tap( this.constructor.name, ( compilation ) => {
compilation.hooks.processAssets.tap( { name: this.constructor.name }, () => {
[ ...compilation.entrypoints ].forEach( ( [ entryName, entrypoint ] ) => {
const chunk = entrypoint.chunks.find( ( { name } ) => name === entryName );
if ( ! chunk ) {
return;
}
this.addAssetFileToEntrypoint( compilation, entryName, chunk );
} );
} );
} );
}
插件在 Webpack 的 thisCompilation 阶段注册监听,再于每个 compilation 的 processAssets 阶段(即资源处理阶段)遍历所有 entrypoint,找到与入口同名的 chunk,为每个 chunk 生成对应的资产文件。从源码结构看,它只处理 entry chunk,不处理异步加载的代码分割 chunk。
2. 提取 JS 产物文件名
getFileFromChunk( chunk: Chunk ) {
return [ ...chunk.files ].find( ( f ) => /\.js$/i.test( f ) );
}
从 chunk 的输出文件列表中找出第一个 .js 文件(不区分大小写)。若找不到 JS 文件(例如入口只产出 CSS),插件会直接跳过该入口。
3. 收集依赖 handle
getDepsHandlesFromChunk( compilation: Compilation, chunk: Chunk ) {
const depsSet = new Set< string >();
compilation.chunkGraph.getChunkModules( chunk ).forEach( ( module ) => {
const theModule = module as Module;
[ ...( theModule.modules || [] ), theModule ].forEach( ( subModule ) => {
const depHandle = transformRequestToHandle( subModule.userRequest, this.options.map );
if ( depHandle ) {
depsSet.add( depHandle );
}
} );
} );
return [ ...depsSet ];
}
这里通过 compilation.chunkGraph.getChunkModules() 拿到 chunk 下的全部模块,对每个模块(及其可能存在的子模块)读取 userRequest(即源码中的 import 路径),交给 transformRequestToHandle 按映射表转换为 handle,用 Set 天然去重。
4. 写入资产文件
const assetFilePath = createAssetFilePath( compilation.getPath( '[file]', { filename: chunkJSFile } ) );
compilation.assets[ assetFilePath ] = new sources.RawSource( getAssetFileContent( entryHandle, depsHandles ) );
chunk.files.add( assetFilePath );
插件把生成的 PHP 内容以 RawSource 形式挂到 compilation.assets 上,并把它加入 chunk 的文件集合,Webpack 会在 emit 阶段将其写到输出目录——全程无需额外文件系统写入,完全走 Webpack 的内存编译管线。
三、输出文件解析:.asset.php 的生成模板
文件命名与内容生成都在 utils.ts 中:
export function createAssetFilePath( path: string, suffix = '.asset.php' ) {
return path.replace( /(\.min)?\.js$/i, suffix );
}
命名规则为:把 JS 文件名中的 .js(或 .min.js)替换为 .asset.php。例如:
| 构建产物 | 生成的资产文件 |
|---|---|
app.js |
app.asset.php |
app.min.js |
app.asset.php |
extension.js |
extension.asset.php |
内容模板:
export function getAssetFileContent( entryHandle: string, depsHandles: string[] ) {
const depsAsString = depsHandles
.filter( ( dep ) => dep !== entryHandle )
.sort()
.map( ( dep ) => `'${ dep }',` )
.join( '\n\t\t' );
return `<?php
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* This file is generated by Webpack, do not edit it directly.
*/
return [
'handle' => '${ entryHandle }',
'deps' => [
${ depsAsString }
],
];
`;
}
几个值得注意的实现细节:
- ABSPATH 防护:文件头部带有
if ( ! defined( 'ABSPATH' ) ) { exit; },防止在 WordPress 环境外被直接访问,这与 WP 插件/主题的常规防护写法一致; - 自依赖剔除:
deps会过滤掉与入口自身 handle 相同的项(filter( ( dep ) => dep !== entryHandle )),避免脚本把自身声明为依赖; - 确定性排序:
deps数组按字典序sort(),保证同一依赖集合在任何构建环境下输出完全一致,利于缓存与快照对比; - 注释声明:文件头明确标注「This file is generated by Webpack, do not edit it directly」,提示这是构建产物,不应手工修改。
四、配置项详解:handle 与 map
插件构造器接受一个 Options 对象(见 plugin.ts 顶部类型定义):
type Options = {
handle: ( entryName: string ) => string;
map: RequestToHandleMap;
};
handle: ( entryName ) => string
一个把「Webpack 入口名」转换为「WP 脚本 handle」的函数。测试中的典型用法是给入口名加统一前缀:
handle: ( entryName ) => `elementor-v2-${ entryName }`,
这样入口 app 会得到 handle elementor-v2-app,入口 util 得到 elementor-v2-util,在 WP 全局脚本命名空间下有效避免 handle 冲突。
map: RequestToHandleMap
请求路径到 handle 的映射表,类型定义在 types.ts:
export type RequestToHandleMap = Array< {
request: string | RegExp;
handle: string;
} >;
匹配规则在 transformRequestToHandle 中实现,存在两种形态:
- 字符串:会被包装成
^request$的精确匹配正则,即只匹配完全相等的 import 路径; - 正则:直接作为正则使用,且替换时使用
request.replace( requestRegex, handle ),因此 handle 中可以包含$1、$2等捕获组引用。
测试中给出的完整示例(见 index.test.ts):
map: [
{ request: 'react', handle: 'react' },
{ request: 'react-dom', handle: 'react-dom' },
{ request: /^@elementor\/(.+)$/, handle: 'elementor-v2-$1' },
{ request: /^@wordpress\/(.+)$/, handle: 'wp-$1' },
],
其效果是把 @elementor/editor 映射为 elementor-v2-editor、把 @wordpress/element 映射为 wp-element、把 react 映射为 react,正好对应快照中 deps 数组里出现的四个 handle。
映射表按数组顺序依次尝试,命中第一个匹配项即返回,因此更具体的规则(如精确字符串)建议放在前面,宽泛的正则规则放在后面。
五、集成测试与输出快照:用 memfs 验证端到端行为
插件配套了一个完整的 Webpack 集成测试(index.test.ts),它把 fs mock 成 memfs 内存文件系统,构造了三个入口 app、extension、util,每个入口都 import 了 @elementor/editor、@wordpress/element、@other/package、react、react-dom 五个包,并用 externals 声明这些包为外部依赖(这样 Webpack 不会真的去解析它们)。
随后运行真实 Webpack 编译,断言:
- 编译无错误、无警告;
- 输出目录下生成了
app.asset.php、extension.asset.php、util.asset.php三个文件; - 每个文件内容与快照一致。
快照文件 展示了 app.asset.php 的最终形态:
<?php
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* This file is generated by Webpack, do not edit it directly.
*/
return [
'handle' => 'elementor-v2-app',
'deps' => [
'elementor-v2-editor',
'react',
'react-dom',
'wp-element',
],
];
注意:源码里 @other/package 被 import 了,但 map 中没有对应的映射规则,因此 transformRequestToHandle 对它返回 undefined,depsSet 会把它过滤掉——这正好验证了「未在 map 中声明的依赖不会被写入 deps」的行为。
六、CHANGELOG 版本演进:从 0.2.1 到 0.3.6 的关键工程决策
CHANGELOG.md 采用 Conventional Commits 规范记录版本变化。逐条解读如下:
0.2.1(2023-07-02)—— 首个记录版本
仅有版本号记录(Version bump only),属于 monorepo(lerna/turbo 风格)发布流程中的纯版本同步,无功能变化。这是该包纳入统一发布体系后的基线版本。
0.3.0(2023-07-11)—— 简化逻辑(Features)
条目为 **webpack-plugins:** simplify logic。结合当前 plugin.ts 的实现来看,插件现在的处理逻辑非常收敛:一次 processAssets 遍历、一个 getDepsHandlesFromChunk 收集函数、一个 getAssetFileContent 模板函数。可以从源码结构推断,0.3.0 把早期版本中更复杂的依赖遍历/文件写入逻辑收敛到了这套简洁的实现上。
0.3.1、0.3.2 —— 发布流程版本同步
两条均为 Version bump only(2023-10-19、2024-07-16),无功能或修复变更,说明该插件随 monorepo 其他包一起发版,保持版本节奏统一。
0.3.3(2024-08-05)—— 只发布必要文件到 npm(Bug Fixes)
条目为 publish only necessary files to npm。这一决策落实在 package.json 的 files 字段上:
"files": [
"README.md",
"CHANGELOG.md",
"/dist",
"/src",
"!**/__tests__"
]
即发布到 npm 的包只包含 README.md、CHANGELOG.md、构建产物 dist/ 和源码 src/,并显式排除所有 __tests__ 目录。这样既保留了 TypeScript 源码便于调试溯源,又避免把测试文件与快照打进发布包,减小包体积。
0.3.4 —— 修复 package.json 的 exports 字段(Bug Fixes)
条目为 Fix package.json exports field。当前 package.json 中的 exports 配置为:
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.js"
},
"./package.json": "./package.json"
}
这是一个典型的双格式(dual package)导出:ESM 环境走 import 指向的 dist/index.mjs,CommonJS 环境走 require 指向的 dist/index.js,TypeScript 类型声明统一指向 dist/index.d.ts,同时单独暴露 ./package.json 子路径。0.3.4 修复的正是这类导出字段的兼容性问题(例如导出条件顺序、子路径缺失等),确保 import 与 require 两种消费方式都能正确解析到插件入口。
0.3.5 —— 在 peerDependencies 中指定具体的 webpack 版本
条目为 Set specific webpack version in peer dependencies。对应 package.json:
"peerDependencies": {
"webpack": "^5.0.0"
}
由于插件直接依赖 Webpack 的 Compiler、Compilation、Chunk、sources 等公开 API(见 plugin.ts 顶部的 import),其行为与 Webpack 主版本强耦合。把 webpack: ^5.0.0 声明为 peer 依赖,等于明确告知使用者「请自行安装 Webpack 5,且插件保证与 Webpack 5 兼容」,避免宿主项目安装不兼容的 Webpack 版本。
0.3.6 —— 移除副作用(Remove side-effects)
条目为 Remove side-effects。这是构建产物体积优化中常见的一环:在包的 package.json 中声明 "sideEffects": false(或通过构建工具配置),让打包器(Webpack、Rollup、esbuild)在对该包做 tree-shaking 时,可以安全地摇掉未被引用的模块。对本插件而言,其纯函数实现(createAssetFilePath、getAssetFileContent、transformRequestToHandle)本身无副作用,声明后能有效降低被引入时的冗余代码。
版本脉络小结
| 版本 | 日期 | 类型 | 核心变更 |
|---|---|---|---|
| 0.2.1 | 2023-07-02 | 版本同步 | monorepo 发布基线 |
| 0.3.0 | 2023-07-11 | Feature | 简化插件逻辑 |
| 0.3.1 / 0.3.2 | 2023-10-19 / 2024-07-16 | 版本同步 | 跟随 monorepo 发版 |
| 0.3.3 | 2024-08-05 | Bug Fix | 仅发布必要文件到 npm |
| 0.3.4 | — | Bug Fix | 修复 exports 字段 |
| 0.3.5 | — | Bug Fix | 固定 webpack peer 依赖版本 |
| 0.3.6 | — | Patch | 移除副作用声明 |
从演进脉络可以看出,该插件经历了「逻辑收敛 → 发布规范 → 消费兼容」三个阶段:先简化核心实现,再通过 files 字段控制 npm 包内容,最后用 exports、peerDependencies、sideEffects 等元数据字段完善现代打包器下的消费体验。截至本文写作时,package.json 中的版本号已推进到 4.4.0,CHANGELOG 记录的 0.x 时代代表的是该插件早期迭代历程。
七、在自己的项目中接入
基于仓库中的测试与源码,一个最小可运行的接入配置如下(参考 index.test.ts 的 webpack 配置):
const { GenerateWordPressAssetFileWebpackPlugin } = require(
'@elementor/generate-wordpress-asset-file-webpack-plugin'
);
module.exports = {
mode: 'production',
entry: {
app: './src/app.js',
},
output: {
filename: '[name].js',
path: __dirname + '/dist',
},
externals: {
react: 'React',
'react-dom': 'ReactDOM',
'@wordpress/element': 'wp.element',
},
plugins: [
new GenerateWordPressAssetFileWebpackPlugin( {
handle: ( entryName ) => `my-plugin-${ entryName }`,
map: [
{ request: 'react', handle: 'react' },
{ request: 'react-dom', handle: 'react-dom' },
{ request: /^@wordpress\/(.+)$/, handle: 'wp-$1' },
],
} ),
],
};
接入要点:
- 包要求宿主环境提供
webpack@^5.0.0(见 package.json 的 peerDependencies),并支持 ESM/CJS 双入口与 TypeScript 类型(dist/index.d.ts); - 被映射的共享库建议同时配置在
externals中,避免 Webpack 重复打包这些依赖——测试中正是靠externals让react、@wordpress/element等包免于真实解析; - 构建完成后,在 PHP 侧用
require读取生成的.asset.php,把其中的deps数组传入wp_register_script即可让 WordPress 自动按依赖顺序加载脚本。
八、总结
@elementor/generate-wordpress-asset-file-webpack-plugin 是 Elementor 前端工程化体系中「构建产物 ↔ WordPress 运行时」之间的桥梁:它把 Webpack 的 chunk 模块依赖分析结果,转换成 WordPress 约定俗成的 handle + deps 数据结构,并以 .asset.php 文件的形式随构建产物一并输出。其核心价值在于三点:自动化(消灭手工维护 $deps)、确定性(Set 去重 + sort() 排序保证输出稳定)、生态对齐(遵循 WordPress ABSPATH 防护与 PHP 返回数组的惯例)。
从 CHANGELOG.md 的演进记录可以清晰看到,一个成熟的开源构建插件在功能稳定后,真正的打磨重点会转向发布规范(files 裁剪)、消费兼容(exports 双格式)、依赖边界(peerDependencies)与产物体积(sideEffects)等工程细节。如果你想深入源码,建议从 plugin.ts 的主流程读起,配合 index.test.ts 与 快照 对照验证,即可完整掌握这套依赖清单生成方案。