@taro-hmr-compile/plugin-webpack 0.0.1-alpha.3

package/src/compile/hmr-compiler-plugin.ts

@@ -0,0 +1,191 @@
+import path from 'path'
+import {resolveMainFilePath} from '@tarojs/helper'
+import type {IPaths} from '@tarojs/service'
+import type {AppConfig} from '@tarojs/taro'
+import {SyncHook} from 'tapable'
+import type {Chunk, Compilation, Compiler} from 'webpack'
+import {ConcatSource, RawSource} from 'webpack-sources'
+import type {Source} from 'webpack-sources'
+import {HMR_PATCH_ASSET} from '../constants'
+import {clearCompiledPages, isPageCompiled, markPageCompiled} from './compile-state'
+import {getAllPages} from '../utils'
+
+const PLUGIN_NAME = 'HmrCompilerPlugin'
+
+type StyleFilename = NonNullable<Compiler['options']['output']['cssFilename']>
+
+export interface HmrCompilerPluginOptions {
+    paths: IPaths
+    appConfig: AppConfig
+    styleFilename?: StyleFilename
+}
+
+export interface HmrCompilerHooks {
+    compileRequested: SyncHook<[page: string]>
+}
+
+export interface HmrCompilationHooks {
+    pageChunkModules: SyncHook<[source: string]>
+}
+
+export const applyPatchBeforeStartup = (source: Source, request: string) => {
+    const patchRequest = JSON.stringify(`${request}.js`)
+    return new ConcatSource(
+        `globalThis.miniHmrApplyPatch(require(${patchRequest}));\n`,
+        source,
+    )
+}
+
+export class HmrCompilerPlugin {
+    private static readonly compilerHooksMap = new WeakMap<Compiler, HmrCompilerHooks>()
+
+    private static readonly compilationHooksMap = new WeakMap<Compilation, HmrCompilationHooks>()
+
+    private compiler?: Compiler
+
+    private hasCompletedInitialBuild = false
+
+    // 页面编译请求可能在任意时刻到达。先排队到下一轮 watchRun，避免与正在执行的编译相互覆盖。
+    private readonly pendingFiles = new Set<string>()
+
+    // 当前编译批次的文件快照。与 pendingFiles 分离，确保编译期间新到达的请求留给下一批处理。
+    private readonly rebuildingFiles = new Set<string>()
+
+    constructor(private readonly options: HmrCompilerPluginOptions) {}
+
+    static getCompilerHooks(compiler: Compiler): HmrCompilerHooks {
+        let hooks = HmrCompilerPlugin.compilerHooksMap.get(compiler)
+        if (!hooks) {
+            hooks = {compileRequested: new SyncHook(['page'])}
+            HmrCompilerPlugin.compilerHooksMap.set(compiler, hooks)
+        }
+        return hooks
+    }
+
+    static getCompilationHooks(compilation: Compilation): HmrCompilationHooks {
+        let hooks = HmrCompilerPlugin.compilationHooksMap.get(compilation)
+        if (!hooks) {
+            hooks = {pageChunkModules: new SyncHook(['source'])}
+            HmrCompilerPlugin.compilationHooksMap.set(compilation, hooks)
+        }
+        return hooks
+    }
+
+    apply(compiler: Compiler) {
+        this.compiler = compiler
+
+        HmrCompilerPlugin.getCompilerHooks(compiler).compileRequested.tap(PLUGIN_NAME, page => {
+            this.requestCompile(page)
+        })
+
+        compiler.hooks.watchRun.tap(PLUGIN_NAME, currentCompiler => {
+            if (this.pendingFiles.size === 0) return
+
+            // 页面是否使用 Shell 由内存中的 compile-state 决定，源文件本身没有发生变化。
+            // 因此需要把请求显式加入 modifiedFiles，并保存当前批次供 needBuild 强制重建。
+            this.rebuildingFiles.clear()
+            this.pendingFiles.forEach(file => this.rebuildingFiles.add(file))
+            currentCompiler.modifiedFiles = new Set([...(currentCompiler.modifiedFiles ?? []), ...this.pendingFiles])
+            this.pendingFiles.clear()
+        })
+
+        compiler.hooks.compilation.tap(PLUGIN_NAME, compilation => {
+            const pages = new Set(getAllPages(this.options.appConfig))
+            const isPageChunk = (chunk: Chunk) => this.isPageChunk(compilation, pages, chunk)
+            const hmrHooks = HmrCompilerPlugin.getCompilationHooks(compilation)
+            const javascriptHooks = compiler.webpack.javascript.JavascriptModulesPlugin.getCompilationHooks(compilation)
+
+            // 只修改 Page Chunk 的 JS transport。Webpack 的 ModuleGraph / ChunkGraph 保持不变，
+            // 因而 hash、HMR diff 和 hot-update 仍以完整模块图为准。
+            javascriptHooks.renderChunk.tap({name: PLUGIN_NAME, stage: -10_000}, (source, {chunk}) => {
+                if (!isPageChunk(chunk)) return source
+                hmrHooks.pageChunkModules.call(source.source().toString())
+                return new RawSource('{}')
+            })
+
+            javascriptHooks.renderStartup.tap(PLUGIN_NAME, (source, _module, {chunk}) => {
+                if (!isPageChunk(chunk)) return source
+
+                const filenameTemplate = compiler.webpack.javascript.JavascriptModulesPlugin
+                    .getChunkFilenameTemplate(chunk, compilation.outputOptions)
+                const assetName = compilation.getPath(filenameTemplate, {
+                    chunk,
+                    contentHashType: 'javascript',
+                    hash: compilation.hash,
+                })
+                const patchModule = HMR_PATCH_ASSET.replace(/\.js$/, '')
+                const relativePath = path.posix.relative(path.posix.dirname(assetName), patchModule)
+                const request = relativePath.startsWith('.') ? relativePath : `./${relativePath}`
+
+                // 微信要求 Page() 在当前页面脚本的同步执行阶段完成。bootstrap 会同步补齐工厂，
+                // update 继续异步排队，因此这里不能用 Promise.then 包裹 Webpack startup。
+                return applyPatchBeforeStartup(source, request)
+            })
+
+            compiler.webpack.NormalModule.getCompilationHooks(compilation).needBuild.tapAsync(
+                PLUGIN_NAME,
+                (module, _context, callback) => {
+                    const [resourcePath] = module.resource?.split('?') ?? []
+                    // 绕过 Webpack 的模块缓存，让 loader 根据最新 compile-state 将页面 Shell 替换为真实页面。
+                    if (resourcePath && this.rebuildingFiles.has(resourcePath)) return callback(null, true)
+                    callback()
+                },
+            )
+
+            const stage = compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT
+            compilation.hooks.processAssets.tap({name: PLUGIN_NAME, stage}, () => {
+                if (!this.hasCompletedInitialBuild && compilation.hash && compilation.errors.length === 0) {
+                    this.emitMissingPageStyleAssets(compilation)
+                }
+            })
+        })
+
+        compiler.hooks.afterEmit.tap(PLUGIN_NAME, compilation => {
+            const isSuccessful = compilation.errors.length === 0 && Boolean(compilation.hash)
+            this.hasCompletedInitialBuild = this.hasCompletedInitialBuild || isSuccessful
+        })
+
+        // 当前批次完成后释放快照；编译期间新进入 pendingFiles 的请求不会被清理。
+        compiler.hooks.done.tap(PLUGIN_NAME, () => this.rebuildingFiles.clear())
+
+        compiler.hooks.watchClose.tap(PLUGIN_NAME, () => this.reset())
+    }
+
+    private requestCompile(page: string) {
+        try {
+            if (isPageCompiled(this.options.paths.appPath, page)) return
+            // loader 在下一轮构建中读取该状态；必须先标记，再触发 watch invalidation。
+            markPageCompiled(this.options.paths.appPath, page)
+            this.pendingFiles.add(resolveMainFilePath(path.resolve(this.options.paths.sourcePath, page)))
+            this.compiler?.watching?.invalidate()
+        } catch (error) {
+            console.error('[taro-hmr-compile] 页面编译触发失败', error)
+        }
+    }
+
+    private isPageChunk(compilation: Compilation, pages: Set<string>, chunk: Chunk) {
+        if (chunk.name && pages.has(chunk.name)) return true
+        return Array.from(pages).some(page => compilation.entrypoints.get(page)?.getEntrypointChunk() === chunk)
+    }
+
+    /** PageShell 不包含真实页面的样式依赖，为缺失的页面样式补充空资产。 */
+    private emitMissingPageStyleAssets(compilation: Compilation) {
+        const {appConfig, styleFilename} = this.options
+        if (!styleFilename) return
+
+        getAllPages(appConfig).forEach(page => {
+            const chunk = compilation.entrypoints.get(page)?.getEntrypointChunk()
+            if (!chunk) return
+
+            const assetName = compilation.getPath(styleFilename, {chunk, contentHashType: 'css/mini-extract'})
+            if (!compilation.getAsset(assetName)) compilation.emitAsset(assetName, new RawSource(''))
+        })
+    }
+
+    private reset() {
+        clearCompiledPages(this.options.paths.appPath)
+        this.hasCompletedInitialBuild = false
+        this.rebuildingFiles.clear()
+        this.pendingFiles.clear()
+    }
+}

package/src/compile/inject-app-hmr-runtime.ts

@@ -0,0 +1,44 @@
+import template from '@babel/template'
+import traverse from '@babel/traverse'
+import generator from '@babel/generator'
+import parser from '@babel/parser'
+import webpack from "webpack";
+
+export const injectAppHmrRuntime = (source: string) => {
+    const ast = parser.parse(source, {sourceType: 'module', plugins: ['typescript', 'jsx']})
+
+    const buildHmrCode = template.statements(`
+      import { mergePatches, injectHmrLifecycle } from '@taro-hmr-compile/core/runtime'
+      injectHmrLifecycle()
+      globalThis.miniHmrApplyPatch = (patches)=>{
+        const bootstrapPatch = patches.find(patch => patch.type === 'bootstrap')
+        return __webpack_require__.miniHmr.applyPatch(bootstrapPatch).then(() => {
+          const updatePatch = mergePatches(${webpack.RuntimeGlobals.getFullHash}(), patches)
+          return __webpack_require__.miniHmr.applyPatch(updatePatch)
+        }).catch(error => {
+          console.error('[taro-hmr-compile] patch apply failed', error)
+        })
+      };
+    `, {placeholderPattern: false})
+
+    traverse(ast, {
+        Program(path) {
+            const body = path.get('body')
+
+            const hasInjected = body.some(item => {
+                return item.isImportDeclaration() && item.node.source.value === '@taro-hmr-compile/core/runtime'
+            })
+
+            if (hasInjected) return
+
+            const nodes = buildHmrCode()
+
+            const lastImport = [...body].reverse().find(item => item.isImportDeclaration())
+
+            if (lastImport) lastImport.insertAfter(nodes)
+
+            if (!lastImport) path.unshiftContainer('body', nodes)
+        }
+    })
+    return generator(ast).code
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+export const HMR_OUTPUT_PATH = 'hmr'
+
+export const HMR_PATCH_ASSET = `${HMR_OUTPUT_PATH}/patch.js`
+
+export const DEFAULT_HMR_PATCH_HISTORY_LIMIT = 20

package/src/index.ts

@@ -0,0 +1,67 @@
+import type {IPluginContext} from '@tarojs/service'
+import type {AppConfig} from '@tarojs/taro'
+import {HMR_OUTPUT_PATH} from './constants'
+import {getAppConfig} from './utils'
+import {HmrCompilerPlugin} from './compile/hmr-compiler-plugin'
+import {HmrPatchPlugin} from './patch/hmr-patch-plugin'
+import {HmrServerPlugin} from './server/hmr-server-plugin'
+import {setupReactRefresh} from '@taro-hmr-compile/react-refresh/compiler'
+import {emptyDirFile} from '@taro-hmr-compile/core/compiler'
+
+export interface WebpackHmrCompileOpt {
+    host: string
+    port: number
+    patchHistoryLimit: number
+}
+
+export default (ctx: IPluginContext, pluginOpts: Partial<WebpackHmrCompileOpt>) => {
+    if (!ctx.runOpts.options?.isWatch) return
+
+    const {appPath, sourcePath, outputPath} = ctx.paths
+
+    const {framework} = ctx.initialConfig
+
+    const appConfig: AppConfig = getAppConfig(ctx)
+
+    const host = pluginOpts.host ?? '127.0.0.1'
+    const port = pluginOpts.port ?? 8080
+    const compileUrl = `http://${host}:${port}/compile`
+
+    setupReactRefresh(ctx)
+
+    ctx.onBuildStart(() => emptyDirFile(outputPath))
+
+    ctx.modifyRunnerOpts(({ opts }) => {
+        opts.output ??= {}
+        opts.output.clean = false
+    })
+
+    ctx.modifyWebpackChain(({chain, webpack}) => {
+
+        chain.module
+            .rule('hmr-compile')
+            .test(/\.[jt]sx?$/)
+            .include.add(ctx.paths.sourcePath)
+            .end()
+            .use('hmr-compile-loader')
+            .loader(require.resolve('./compile/hmr-compile-loader'))
+            .options({appPath, sourcePath, appConfig, framework, compileUrl})
+            .end()
+
+        chain.output
+            .set('hotUpdateChunkFilename', `${HMR_OUTPUT_PATH}/[id].[fullhash].hot-update.js`)
+            .set('hotUpdateMainFilename', `${HMR_OUTPUT_PATH}/[runtime].[fullhash].hot-update.json`)
+
+        const {patchHistoryLimit} = pluginOpts
+
+        const [{filename: styleFilename}] = chain.plugin('miniCssExtractPlugin')?.get('args') || []
+
+        chain.plugin('hmr-compiler-plugin').use(HmrCompilerPlugin, [{paths: ctx.paths, appConfig, styleFilename}])
+
+        chain.plugin('hmr-plugin').use(webpack.HotModuleReplacementPlugin)
+
+        chain.plugin('hmr-patch-plugin').use(HmrPatchPlugin, [{patchHistoryLimit}])
+
+        chain.plugin('hmr-server-plugin').use(HmrServerPlugin, [{host, port}])
+    })
+}

package/src/patch/hmr-patch-manager.ts

@@ -0,0 +1,102 @@
+import type {Expression} from '@babel/types'
+
+export interface BootstrapPatchSource {
+    type: 'bootstrap'
+    moduleFactories: Map<string, Expression>
+}
+
+export interface UpdatePatchSource {
+    type: 'update'
+    fromHash: string
+    toHash: string
+    moduleFactories: Map<string, Expression>
+    removedModules: string[]
+}
+
+export type PatchSource = BootstrapPatchSource | UpdatePatchSource
+
+/** 合并两个连续 update，并按后一份 update 的最终模块状态解决修改和删除冲突。 */
+const mergeUpdatePatches = (basePatch: UpdatePatchSource, nextPatch: UpdatePatchSource): UpdatePatchSource => {
+    if (basePatch.toHash !== nextPatch.fromHash) {
+        throw new Error(`[taro-hmr-compile] 无法合并不连续的 HMR patch：${basePatch.toHash} !== ${nextPatch.fromHash}`)
+    }
+
+    const moduleFactories = new Map(basePatch.moduleFactories)
+    const removedModules = new Set(basePatch.removedModules)
+
+    nextPatch.moduleFactories.forEach((factory, moduleId) => {
+        moduleFactories.set(moduleId, factory)
+        removedModules.delete(moduleId)
+    })
+    nextPatch.removedModules.forEach(moduleId => {
+        moduleFactories.delete(moduleId)
+        removedModules.add(moduleId)
+    })
+
+    return {
+        type: 'update',
+        fromHash: basePatch.fromHash,
+        toHash: nextPatch.toHash,
+        moduleFactories,
+        removedModules: Array.from(removedModules),
+    }
+}
+
+/** 仅维护 bootstrap/update Patch 状态、连续性和压缩，不依赖 Webpack 编译对象。 */
+export class HmrPatchManager {
+    private bootstrapPatch?: BootstrapPatchSource
+
+    private compactedUpdatePatch?: UpdatePatchSource
+
+    private readonly recentUpdatePatches: UpdatePatchSource[] = []
+
+    private readonly limit: number
+
+    constructor(limit: number) {
+        this.limit = Math.max(1, limit)
+    }
+
+    clear() {
+        this.bootstrapPatch = undefined
+        this.clearUpdateHistory()
+    }
+
+    setBootstrap(moduleFactories: Map<string, Expression>) {
+        this.bootstrapPatch = moduleFactories.size > 0
+            ? {type: 'bootstrap', moduleFactories: new Map(moduleFactories)}
+            : undefined
+    }
+
+    /** 追加 update；发现 hash 不连续时丢弃旧 update 链，并在追加后执行容量压缩。 */
+    appendUpdate(patch: UpdatePatchSource) {
+        const latestPatch = this.recentUpdatePatches[this.recentUpdatePatches.length - 1] ?? this.compactedUpdatePatch
+        if (latestPatch && latestPatch.toHash !== patch.fromHash) this.clearUpdateHistory()
+        this.recentUpdatePatches.push(patch)
+        this.compactUpdateHistory()
+    }
+
+    /** 按客户端消费顺序返回 bootstrap、压缩 update 与近期 update。 */
+    getPatches(): PatchSource[] {
+        const updatePatches = this.compactedUpdatePatch
+            ? [this.compactedUpdatePatch, ...this.recentUpdatePatches]
+            : this.recentUpdatePatches
+        return this.bootstrapPatch
+            ? [this.bootstrapPatch, ...updatePatches]
+            : updatePatches
+    }
+
+    private clearUpdateHistory() {
+        this.compactedUpdatePatch = undefined
+        this.recentUpdatePatches.length = 0
+    }
+
+    /** 将超出上限的旧 update 逐步合并到首个 update；bootstrap 永不参与 merge。 */
+    private compactUpdateHistory() {
+        while (this.recentUpdatePatches.length > this.limit) {
+            const oldestUpdatePatch = this.recentUpdatePatches.shift()!
+            this.compactedUpdatePatch = this.compactedUpdatePatch
+                ? mergeUpdatePatches(this.compactedUpdatePatch, oldestUpdatePatch)
+                : oldestUpdatePatch
+        }
+    }
+}

package/src/patch/hmr-patch-plugin.ts

@@ -0,0 +1,237 @@
+import generator from '@babel/generator'
+import {parse} from '@babel/parser'
+import template from '@babel/template'
+import traverse from '@babel/traverse'
+import * as t from '@babel/types'
+import type {Compilation, Compiler} from 'webpack'
+import {RawSource} from 'webpack-sources'
+import {DEFAULT_HMR_PATCH_HISTORY_LIMIT, HMR_PATCH_ASSET} from '../constants'
+import {HmrCompilerPlugin} from '../compile/hmr-compiler-plugin'
+import {HmrPatchManager} from '../patch/hmr-patch-manager'
+import type {PatchSource, UpdatePatchSource} from '../patch/hmr-patch-manager'
+import {HmrPatchRuntimePlugin} from './hmr-patch-runtime-plugin'
+
+const PLUGIN_NAME = 'HmrPatchPlugin'
+const HOT_UPDATE_MANIFEST_SUFFIX = '.hot-update.json'
+const HOT_UPDATE_SCRIPT_SUFFIX = '.hot-update.js'
+const HOT_UPDATE_HASH_PATTERN = /\.([0-9a-f]+)\.hot-update\.json$/i
+const STYLE_ASSET_PATTERN = /\.(?:css|wxss|acss|ttss|qss|jxss)(?:\.map)?$/i
+const TEMPLATE_RUNTIME_ASSET_PATTERN = /(?:^|\/)(?:base\.wxml|utils\.wxs)$/i
+
+interface HotUpdateManifest {
+    m?: Array<string | number>
+}
+
+type CompilationAsset = ReturnType<Compilation['getAssets']>[number]
+
+interface HotUpdateAssets {
+    manifests: CompilationAsset[]
+    scripts: CompilationAsset[]
+}
+
+export interface HmrPatchPluginOptions {
+    patchHistoryLimit?: number
+}
+
+const collectModuleFactories = (source: string, moduleFactories: Map<string, t.Expression>) => {
+    const ast = parse(`(${source})`, {sourceType: 'script'})
+    const statement = ast.program.body[0]
+    if (!t.isExpressionStatement(statement) || !t.isObjectExpression(statement.expression)) {
+        throw new Error('[taro-hmr-compile] Page Chunk 模块段不是对象表达式')
+    }
+
+    statement.expression.properties.forEach(property => {
+        if (!t.isObjectProperty(property) || !t.isExpression(property.value)) {
+            throw new Error('[taro-hmr-compile] Page Chunk 模块对象包含无法识别的属性')
+        }
+
+        const {key} = property
+        let moduleId: string
+        if (t.isStringLiteral(key) || t.isNumericLiteral(key)) moduleId = String(key.value)
+        else if (t.isIdentifier(key) && !property.computed) moduleId = key.name
+        else throw new Error('[taro-hmr-compile] Page Chunk 模块对象包含无法识别的模块 ID')
+
+        moduleFactories.set(moduleId, property.value)
+    })
+}
+
+/** 将本轮 Webpack hot-update 产物转换为内部 update 表示。 */
+const createUpdatePatch = (toHash: string, assets: HotUpdateAssets): UpdatePatchSource => {
+    const manifestAsset = assets.manifests[0]
+    const hashMatch = manifestAsset.name.match(HOT_UPDATE_HASH_PATTERN)
+    if (!hashMatch) throw new Error(`[taro-hmr-compile] 无法从 ${manifestAsset.name} 提取 HMR 基线 hash`)
+
+    const moduleFactories = new Map<string, t.Expression>()
+    assets.scripts.forEach(asset => {
+        const ast = parse(asset.source.source().toString(), {sourceType: 'script'})
+
+        traverse(ast, {
+            CallExpression(nodePath) {
+                const {callee} = nodePath.node
+                if (!t.isMemberExpression(callee) || !t.isIdentifier(callee.object, {name: 'wx'})) return
+                if (!t.isStringLiteral(callee.property) || !callee.property.value.startsWith('webpackHotUpdate')) return
+
+                const modules = nodePath.node.arguments[1]
+                if (!t.isObjectExpression(modules)) return
+
+                modules.properties.forEach(property => {
+                    if (!t.isObjectProperty(property) || !t.isExpression(property.value)) {
+                        throw new Error('[taro-hmr-compile] HMR 模块对象包含无法识别的属性')
+                    }
+
+                    const {key} = property
+                    let moduleId: string
+                    if (t.isStringLiteral(key) || t.isNumericLiteral(key)) moduleId = String(key.value)
+                    else if (t.isIdentifier(key) && !property.computed) moduleId = key.name
+                    else throw new Error('[taro-hmr-compile] HMR 模块对象包含无法识别的模块 ID')
+
+                    moduleFactories.set(moduleId, property.value)
+                })
+            },
+        })
+    })
+
+    const removedModules = new Set<string>()
+    assets.manifests.forEach(asset => {
+        const manifest = JSON.parse(asset.source.source().toString()) as HotUpdateManifest
+        manifest.m?.forEach(moduleId => removedModules.add(String(moduleId)))
+    })
+
+    return {
+        type: 'update',
+        fromHash: hashMatch[1],
+        toHash,
+        moduleFactories,
+        removedModules: Array.from(removedModules),
+    }
+}
+
+/** 将内部 Patch 表示序列化为固定 patch.js。 */
+const createPatchAssetSource = (patches: PatchSource[]): string => {
+    const buildBootstrapPatchNode = template.expression(`({
+        type: 'bootstrap',
+        modules: %%MODULES%%
+    })`)
+    const buildUpdatePatchNode = template.expression(`({
+        type: 'update',
+        fromHash: %%FROM_HASH%%,
+        toHash: %%TO_HASH%%,
+        modules: %%MODULES%%,
+        removedModules: %%REMOVED_MODULES%%
+    })`)
+    const patchNodes = patches.map(patch => {
+        const modules = t.objectExpression(Array.from(
+            patch.moduleFactories,
+            ([moduleId, factory]) => t.objectProperty(t.stringLiteral(moduleId), factory),
+        ))
+        if (patch.type === 'bootstrap') return buildBootstrapPatchNode({MODULES: modules})
+
+        return buildUpdatePatchNode({
+            FROM_HASH: t.stringLiteral(patch.fromHash),
+            TO_HASH: t.stringLiteral(patch.toHash),
+            MODULES: modules,
+            REMOVED_MODULES: t.arrayExpression(patch.removedModules.map(moduleId => t.stringLiteral(moduleId))),
+        })
+    })
+
+    const statements = template.statements('module.exports = %%PATCHES%%;')({PATCHES: t.arrayExpression(patchNodes)})
+    return generator(t.program(statements)).code
+}
+
+const isPassthroughAsset = (assetName: string) => {
+    return STYLE_ASSET_PATTERN.test(assetName) || TEMPLATE_RUNTIME_ASSET_PATTERN.test(assetName)
+}
+
+export class HmrPatchPlugin {
+    private hasCompletedInitialBuild = false
+
+    private readonly patchManager: HmrPatchManager
+
+    private readonly emittedAssetSources = new Map<string, string>()
+
+    constructor(options: HmrPatchPluginOptions) {
+        this.patchManager = new HmrPatchManager(options.patchHistoryLimit ?? DEFAULT_HMR_PATCH_HISTORY_LIMIT)
+    }
+
+    apply(compiler: Compiler) {
+        new HmrPatchRuntimePlugin().apply(compiler)
+
+        compiler.hooks.compilation.tap(PLUGIN_NAME, compilation => {
+            const initialPageFactories = new Map<string, t.Expression>()
+
+            HmrCompilerPlugin.getCompilationHooks(compilation).pageChunkModules.tap(PLUGIN_NAME, source => {
+                collectModuleFactories(source, initialPageFactories)
+            })
+
+            // 等 Webpack 生成完整的 hot-update assets 后，再统一转换成固定的 patch.js。
+            const stage = compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_REPORT
+            compilation.hooks.processAssets.tap({name: PLUGIN_NAME, stage}, () => {
+                this.processAssets(compilation, initialPageFactories)
+            })
+        })
+
+        compiler.hooks.afterEmit.tap(PLUGIN_NAME, compilation => {
+            const isSuccessful = compilation.errors.length === 0 && Boolean(compilation.hash)
+            this.hasCompletedInitialBuild = this.hasCompletedInitialBuild || isSuccessful
+        })
+
+        compiler.hooks.watchClose.tap(PLUGIN_NAME, () => this.reset())
+    }
+
+    private processAssets(compilation: Compilation, initialPageFactories: Map<string, t.Expression>) {
+        if (!compilation.hash || compilation.errors.length > 0) return
+
+        const originalAssets = compilation.getAssets()
+        if (!this.hasCompletedInitialBuild) {
+            this.patchManager.clear()
+            this.emittedAssetSources.clear()
+            originalAssets.forEach(asset => {
+                if (isPassthroughAsset(asset.name)) {
+                    this.emittedAssetSources.set(asset.name, asset.source.source().toString())
+                }
+            })
+            this.patchManager.setBootstrap(initialPageFactories)
+            this.emitPatchAsset(compilation, false)
+            return
+        }
+
+        const hotUpdateAssets: HotUpdateAssets = {
+            manifests: originalAssets.filter(asset => asset.name.endsWith(HOT_UPDATE_MANIFEST_SUFFIX)),
+            scripts: originalAssets.filter(asset => asset.name.endsWith(HOT_UPDATE_SCRIPT_SUFFIX)),
+        }
+
+        if (hotUpdateAssets.manifests.length) {
+            this.patchManager.appendUpdate(createUpdatePatch(compilation.hash, hotUpdateAssets))
+            this.emitPatchAsset(compilation, true)
+        }
+
+        // 增量 compilation 仍可能包含普通 chunk 资产，不能让它们覆盖初始 PageShell。
+        this.removeSupersededAssets(compilation, originalAssets)
+    }
+
+    /** 热更新转换完成后，保留固定 patch 与发生变化的模板、平台样式资产。 */
+    private removeSupersededAssets(compilation: Compilation, assets: CompilationAsset[]) {
+        assets.forEach(asset => {
+            if (asset.name === HMR_PATCH_ASSET) return
+            if (!isPassthroughAsset(asset.name)) return compilation.deleteAsset(asset.name)
+
+            const source = asset.source.source().toString()
+            const previousSource = this.emittedAssetSources.get(asset.name)
+            this.emittedAssetSources.set(asset.name, source)
+            if (previousSource === source) compilation.deleteAsset(asset.name)
+        })
+    }
+
+    private emitPatchAsset(compilation: Compilation, isHotUpdate: boolean) {
+        const source = new RawSource(createPatchAssetSource(this.patchManager.getPatches()))
+        const assetInfo = {hotModuleReplacement: isHotUpdate}
+        if (compilation.getAsset(HMR_PATCH_ASSET)) compilation.updateAsset(HMR_PATCH_ASSET, source, assetInfo)
+        else compilation.emitAsset(HMR_PATCH_ASSET, source, assetInfo)
+    }
+
+    private reset() {
+        this.hasCompletedInitialBuild = false
+        this.emittedAssetSources.clear()
+        this.patchManager.clear()
+    }
+}