Parcel Scope Hoisting Packager 原理深度解析从 import 替换到符号解析的完整打包流程【免费下载链接】parcelThe zero configuration build tool for the web. 项目地址: https://gitcode.com/gh_mirrors/pa/parcel本文以 Parcel 仓库中 docs/Scopehoisting Packager.md 为核心骨架结合 ScopeHoistingPackager.js、BundleGraph.js 等源码实现系统讲解 Parcel 生产构建模式下 JS Packager 的打包流程资产如何被加载、判断是否包装wrap、通过正则一次性完成依赖内联与符号替换以及getSymbolResolution如何递归穿透 re-export 找到真正导出该符号的资产。读完本文你将理解 Parcel Scope Hoisting 打包器从package()入口到最终产物生成的完整调用链掌握 wrapped/unwrapped 资产的判别逻辑、符号解析的四种返回形态与 interop 处理并能据此定位构建产物中各种标识符如$id$export$foo、parcelRequire(id).bar的来源。注关于单个资产single asset为何可以被跳过skip而不进入产物属于 Scope Hoisting 的整体概念范畴本文不展开详见 docs/Scopehoisting.md 中的 Skipping assets (deferring and skipping during bundling) 一节。本文聚焦于Scope Hoisting Packager作用域提升打包器本身的打包实现。一、Scope Hoisting Packager 在 Parcel 中的位置在 Parcel 中JS 打包器位于 packages/packagers/js/src/index.js它根据环境配置在两种打包器之间二选一DevPackager开发构建使用采用类似 browserify 的运行时注册表module registry方式每个模块都通过parcelRequire.register包裹依赖通过require调用解析ScopeHoistingPackager生产构建shouldScopeHoist为真使用将多个资产直接拼接进同一作用域用普通变量访问替换parcelRequire(id).foo式的注册表调用从而缩小体积、提升压缩器minifier的效果。源码中可见二者的选择逻辑index.js#L93-L107let packager bundle.env.shouldScopeHoist ? new ScopeHoistingPackager(options, bundleGraph, bundle, config.parcelRequireName, config.unstable_asyncBundleRuntime) : new DevPackager(options, bundleGraph, bundle, config.parcelRequireName);ScopeHoistingPackager 的核心类定义在 packages/packagers/js/src/ScopeHoistingPackager.js共 1500 行构造函数接收bundleGraph、bundle、parcelRequireName、useAsyncBundleRuntime等参数并根据bundle.env.outputFormat选择对应的输出格式实现esmodule→ESMOutputFormatcommonjs→CJSOutputFormatglobal→GlobalOutputFormat其中parcelRequireName的生成逻辑在 index.js#L53-L65读取项目 package.json 的name字段并取哈希后 4 位拼接形如parcelRequirexxxx目的是让同一页面上的多个 Parcel 构建产物可以共存而不冲突。此外JS 打包器还支持一个配置项unstable_asyncBundleRuntime布尔值index.js#L22-L30 中的 schema 校验用于启用实验性的异步 bundle 运行时bundle queue本文后面会涉及它在shouldBundleQueue/runWhenReady中的使用。二、打包入口package()三步主流程package()是打包的起点ScopeHoistingPackager.js#L130-L273整个流程可以概括为文档中描述的三步loadAssets()从缓存中加载所有资产的代码内容并判断哪些资产需要被包装wrapped。processAsset()/visitAsset()→buildAsset()递归解析依赖的 specifier、内联依赖并把结果拼接到顶层res字符串上。启动过程对每个资产调用processAsset()并对已在其他位置被内联过的资产跳过保证每个资产只处理一次。2.1 加载资产与判定 wrappedloadAssets()loadAssets()ScopeHoistingPackager.js#L310-L362使用PromiseQueue最大并发 32并行读取每个资产的代码与 source map并同时判断资产是否需要被parcelRequire.register包装。判定条件满足其一即 wrappedasset.meta.shouldWrap || this.bundle.env.sourceType script || this.bundleGraph.isAssetReferenced(this.bundle, asset) || this.bundleGraph .getIncomingDependencies(asset) .some(dep dep.meta.shouldWrap dep.specifierType ! url)即转换器标记了shouldWrap、环境是 script 类型、资产被其他 bundle 引用、或存在标记为 wrap 的非 URL 类型依赖。同时还有一个特例常量模块constant module即使满足条件也不会被包装除非它被某个 lazy 依赖引用if (!asset.meta.isConstantModule || this.bundleGraph.getIncomingDependencies(asset).some(dep dep.priority lazy)) { this.wrappedAssets.add(asset.id); wrapped.push(asset); }此外一旦某个资产被包装其依赖子树中的所有非常量模块也会被连带包装第二个遍历循环L343-L358因为被包装资产的内部代码无法再引用顶层提升变量必须整体走注册表路径。2.2 主循环wrapped 优先、逐资产拼接package()中有一个内部函数processAsset它调用visitAsset得到[content, map, lines]三元组将其追加到顶层res字符串并累计行数用于 source map 偏移。拼接顺序非常讲究先处理所有 wrapped 资产把它们提升到 bundle 顶部注释原文Hoist wrapped asset to the top of the bundle to ensure that they are registered before they are used保证parcelRequire.register先于使用被调用再遍历与 bundle 直接相连的资产bundle.traverseAssets每个资产处理完后skipChildren因为依赖会通过代码中的import语句替换被处理而不是通过图遍历继续深入。2.3 收尾prelude、entry 执行与 postlude所有资产拼接完毕后package()按顺序完成收尾调用buildBundlePrelude()生成头部interpreter/hashbang、输出格式专属 prelude、按需引入的 helpers、parcelRequire运行时 prelude、worker 的importScripts并将其前置到res对于 wrapped 的 entry 资产追加parcelRequire(publicId);调用以触发执行若是主 entry 且有导出符号则追加var ${entryExports} parcelRequire(...)调用输出格式的buildBundlePostlude()生成尾部对于outputFormat global且sourceType script的 bundle主 entry 会被提升到 bundle 包装之外使其顶层变量成为真实浏览器脚本的全局变量并用replaceScriptDependencies把 runtimes 的依赖引用替换为parcelRequire调用。其中 prelude 的实际代码定义在 packages/packagers/js/src/helpers.js它维护$parcel$modules与$parcel$inits两个对象parcelRequire优先从$parcel$global上取兼容多 bundle 共享同一注册表取不到则现场创建并注册到全局。三、核心构建函数buildAsset()五步内联与替换buildAsset()ScopeHoistingPackager.js#L466-L703是每个资产的处理核心文档将其拆解为五步跳过判断若资产应被跳过则不输出资产本身内容仅递归拼接其依赖资产buildReplacements()生成文本替换用的两张 MapbuildAssetPrelude()按需生成 interop flag 调用与合成的 exports 对象REPLACEMENT_RE正则替换一次性完成 import 内联、符号替换与行数统计按需用parcelRequire.register(id, ...)包装结果。3.1 第一步跳过资产shouldSkipAssetshouldSkipAssetL1491-L1501返回 true 的条件是该资产是 script entryoutputFormat global且sourceType script的主 entry会被提升到 bundle 外或资产无副作用sideEffects false且getUsedSymbols(asset).size 0且未被其他 bundle 引用。被跳过的资产其内容不输出但它的依赖仍会被处理对应文档第 1 条ignore the current asset, callbuildAsset()for dependency assets and concatenate only them together。3.2 第二步构建替换 MapbuildReplacementsbuildReplacements()L705-L810产出两张表依赖表depMap键形如${assetId}:${specifier}${specifiertype}specifierType 仅当为esm时追加:esm后缀值为该 import 对应的Dependency数组。之所以是数组是因为单个 import 语句可能因 re-export 被解析到多个资产源码注释A single${id}:${specifier}:esmmight have been resolved to multiple assets due to reexports。这张表用于解析转换器transformer插入的import id;声明。符号替换表replacements键是依赖符号的本地部分形如$id$import$foo值是getSymbolResolution的解析结果如$id$export$bar或parcelRequire(id).bar。在构建replacements时还处理了几种特殊情况异步依赖lazy优先取bundleGraph.resolveAsyncDependency返回的底层资产若直接解析为资产则替换为Promise.resolve(${symbol})即使所有使用的符号都被静态分析异步依赖仍需要 namespace 对象这是通过转换器写入的dep.meta.promiseSymbol记录并在此处处理的wrapped 资产的 exports 命名空间若资产被包装或 commonjs 输出下的主 entry则把$${assetId}$exports替换回module.exports对应文档第 3 条中for wrapped assets, this has to be replaced back tomodule.exports外部模块external无法解析且非 optional 的依赖调用addExternal()处理详见第七节。3.3 第三步合成资产前导buildAssetPreludebuildAssetPrelude()L1151-L1363返回[prepend, prependLineCount, append]三元组其职责是生成 exports namespace 对象。当资产不满足静态导出staticExports false、被包装、namespace 被使用、或需要 default interop 时会生成var $${assetId}$exports {};若被包装或为 commonjs 主 entry则省略该声明直接使用包装器提供的module.exports。生成__esModuleinterop flag。当资产有default导出且*符号被使用时$parcel$defineInteropFlag($${assetId}$exports);仅为被使用的 re/export 生成$parcel$export/$parcel$exportWildcard调用对应文档including generation of the$parcel$exportand$parcel$exportWildcardcalls only for used re/exports对export * from ...若目标资产被包装或导出不静态追加$parcel$exportWildcard($$assetId$exports, obj);否则逐个对getUsedSymbols(dep)中除default/__esModule外的符号追加$parcel$export(...)对当前资产自身被使用的导出基于getIncomingDependencies的 used symbols而非资产自身的 used exports以便覆盖 re-export 的符号生成 getter/setter$parcel$export($${assetId}$exports, foo, () $id$export$foo);为什么用 getter/setter 而非直接赋值源码注释给出了答案这是为了模拟 ESM 的 live bindings——当原绑定被修改时exports 对象上的属性同步更新比在每个赋值点插入额外语句更简单。这也是文档在 docs/Scopehoisting.md 中强调/*#__PURE__*/注释重要的原因被移除的export语句对应的变量成为死代码纯注释让 minifier 可以安全删除右侧表达式。3.4 第四步单趟正则替换REPLACEMENT_RE这是buildAsset中最精巧的部分。REPLACEMENT_RE定义在 ScopeHoistingPackager.js#L39-L40const REPLACEMENT_RE /\n|import\s([0-9a-f]{16}:.?);|(?:\$[0-9a-f]{16}\$exports)|(?:\$[0-9a-f]{16}\$(?:import|importAsync|require)\$[0-9a-f](?:\$[0-9a-f])?)/g;它在一个正则中同时匹配三类内容源码注释This is all done in a single regex so that we only do one pass over the whole code并同步统计换行数以维护 source map换行符\n不做替换仅推进行计数lineCount与列起点import id;用依赖资产的源码替换递归调用buildAsset()。若被引用资产是 wrapped则不内联而是放进depContent数组、在当前资产之后输出保证循环依赖时模块已注册同时调用getHoistedParcelRequires读取hoistedRequires列表并把需要的parcelRequire调用前置。若当前资产不包装则依赖代码会被拼接到res顶部res depCode \n res;$id$exports在替换表中查找。对于 wrapped 资产前面buildReplacements已把它映射回module.exports$id$import|importAsync|require$foo在replacements表中查找并替换为解析后的标识符若未命中则原样保留replacements.get(m) ?? m。替换过程中还同步维护 source map当替换文本与原文长度不一致时调用sourceMap.offsetColumns修正列偏移依赖被内联时用sourceMap.addSourceMap叠加依赖的 map 并按行数偏移。若整个资产既无依赖也无替换则走countLines(code)的简单路径避免不必要的正则开销。3.5 第五步parcelRequire.register 包装如果资产被判定为 wrappedL668-L692最终代码会被包装为parcelRegister(${publicId}, function(module, exports) { ${code} });随后把depContent中收集的依赖代码追加在包装之后注释Dependencies must be inserted AFTER the asset is registered so that circular dependencies work——循环依赖要求先注册再执行依赖的副作用。此时needsPrelude被置为 true保证parcelRequire运行时 prelude 会被包含进产物。四、符号解析Packager 包装层getSymbolResolution()ScopeHoistingPackager.getSymbolResolution()L983-L1109是围绕bundleGraph.getSymbolResolution()的包装对应文档第 30-45 行。它多接收一个dep参数用于判断两件事是否需要 CJS interop当依赖是 ESM import 时是否是非条件 import此时需要生成提升的parcelRequire调用。parentAsset参数的用途是让被包装的资产在引用自身的 namespace 对象时使用module.exports而非$id$exports对应文档第 36 行。它返回的解析表达式有五种形态文档第 38-43 行返回形式含义$id$export$bar同 bundle 内 ESM 导入静态解析到提升后的顶层变量$id$exports同 bundle 内 ESM 导入namespace 对象id$exports.bar导出无法静态分析时的属性访问parcelRequire(id).bar被包装或在其他 bundle 中($parcel$interopDefault(...))ESM default 导入解析到无法静态分析的 CJS 资产核心逻辑分支如下namespace 请求imported *、exportSymbol *、或 default interop返回 namespace 对象。若资产被包装且引用自身直接返回module.exports属性访问目标被包装、导出非静态、symbol为空、或外部 CJS 库依赖用getPropertyAccess生成obj.exportSymbol或obj[exportSymbol]成员访问若 import 的是default且目标资产有*导出且需要 interop则返回(/*__PURE__*/$parcel$interopDefault(${obj}))直接引用静态导出且已解析出顶层变量symbol返回replacements?.get(symbol) || symbol。getPropertyAccessL450-L456会判断属性名是否为合法标识符合法用.foo否则用[foo]。此外文档还强调该方法会通过变更hoistedRequires列表来跟踪 wrapped 资产的 import第 45 行。当解析结果指向一个 wrapped 资产而该依赖是顶层非条件导入时会记录hoisted.set(resolvedAsset.id, var $${publicId} parcelRequire(${JSON.stringify(publicId)}););这些提升的变量声明随后由getHoistedParcelRequiresL1111-L1149在 import 替换处输出其顺序保证被包装依赖的副作用按源码顺序执行如果解析资产不是hoistedRequires中的第一个还会先插入一个直接的parcelRequire(id);调用确保它先运行。五、BundleGraph 层的递归符号解析bundleGraph.getSymbolResolution()的实现在 packages/core/core/src/BundleGraph.js#L1658。它传递性地/递归地遍历资产的 re-export 链找到指定导出真正被定义的地方对应文档第 47-53 行。这使得解析到的可以是实际的值而不只是某个 re-export 绑定。5.1 解析流程与boundary参数算法核心对应源码 L1658-L1809symbol *时直接返回 namespaceexportSymbol: *否则取asset.symbols.get(symbol).local作为identifier逆序遍历资产的依赖对每个依赖通过symbolLookuplocal - imported反查表判断identifier是否由该依赖 re-export 而来若是递归解析被解析资产上的对应符号对export *情况depSymbols.get(*)?.local *且非default导出递归到被解析资产继续查找若在多个 re-export 中都找到了符号如两个export *冲突则收集potentialResults最终只有一个候选时返回它多个候选时视为 bailout见下文。boundary参数即当前 bundle用于限制递归深度文档第 53 行一旦递归离开当前 bundle解析就停止。原因是资产 A 使用资产 B 的值通常建模为 A→B 的依赖依赖还被用来判断资产是否被其他 bundle 需要从而必须parcelRequire注册。这种跨资产使用但不一定有依赖的不一致discrepancy在单 bundle 内可以处理跨 bundle 则不行所以用boundary截断。源码中assetOutside boundary !this.bundleHasAsset(boundary, asset)正是这一判断。5.2 三种解析结果与 bailout文档第 55-63 行总结了三种可能的解析结果symbol字段找到导出symbol为顶层变量名。返回值包含asset、exportSymbol字符串、symbol值可通过$asset.id$exports[exportSymbol]访问通常也可通过顶层变量symbol直接访问。文档给出的示例对getSymbolResolution(math.js, add)返回{asset: math.js, exportSymbol: add, symbol: $fa6943ce8a6b29$export$add}未找到导出symbol undefined。理论上这种情况应已被 symbol propagation符号传播提前捕获导出存在但未使用symbol false对应源码中依赖被 skip 的分支isDependencySkipped(dep)为真时置为 falsebailout有多个可能性symbol null调用方应回退到$resolvedAsset$exports[exportsSymbol]的运行时属性访问。文档给出了两个典型的 bailout 场景多个冲突的 re-exportexport * from ./nonstatic-cjs1.js; export * from ./nonstatic-cjs1.js;原文如此即两个export *的候选无法在构建期静态决定只能留到运行时决定跟随哪个 re-export目标资产本身是非静态 CJS此时无论如何都应使用module.exports[exportsSymbol]。源码中potentialResults.length 1时返回唯一候选否则进入 bailout 路径found/skipped/identifier的组合与文档描述完全对应。六、prelude、helpers 与输出格式Scope Hoisting 的产物头部prelude在buildBundlePrelude()L1365-L1472中生成内容依次为hashbang主 entry 若记录了 interpreter如#!/usr/bin/env node且不是 async bundle、目标非浏览器则原样输出输出格式专属 prelude由ESMOutputFormat/CJSOutputFormat/GlobalOutputFormat的buildBundlePrelude()生成例如 ESM 格式可能输出import语句——三种输出格式类定义在同目录的 ESMOutputFormat.js、CJSOutputFormat.js、GlobalOutputFormat.js按需 helper根据usedHelpers集合输出对应函数。这些 helper 包括$parcel$global、$parcel$defineInteropFlag、$parcel$export、$parcel$exportWildcard、$parcel$interopDefault、$parcel$import、$parcel$resolve等定义在 helpers.js。helper 的使用情况由转换器写入asset.meta.usedHelpers位掩码见 buildAsset 中 L519-L542以及打包器运行时的按需收集如usedHelpers.add($parcel$interopDefault)运行时 prelude当needsPrelude为真时判断当前 bundle 是否可能是第一个加载的 JS bundlemightBeFirstJS依据父 bundle 类型、是否 entry bundle group、是否 isolated 等若是则输出完整 preludeprelude(parcelRequireName)定义见 helpers.js#L6-L38否则只取现有全局注册表var parcelRequire $parcel$global[...]worker/worklet 的 importScripts为 sibling bundle 输出importScripts(...)或import ...ESM worker 中不允许importScripts。这里可以看到文档反复提到的module registry (prelude)开销来源只有确实需要运行时注册表如跨 bundle 复用、条件 require时prelude 才被包含完全静态的 bundle 可以省掉它。七、边界情况库模式 externals、async bundle 与条件执行7.1 库模式library下的外部依赖在package()开头L139-L151如果目标是 library 构建env.isLibrary或输出格式为 commonjs、或 ESM 但非 async bundle则对每个被引用的 sibling bundle 建立externals映射key 为相对 bundle 路径。库构建的加载器运行时被排除改为在 entry bundle 中为每个 bundle group 添加指向 sibling bundle 的 import供其他打包器如 webpack/rollup后续处理。addExternal()L812-L960负责把未解析的依赖转成外部引用浏览器global输出格式下不支持外部模块直接抛出ThrowableDiagnosticExternal modules are not supported when building for browsercommonjs 输出下为保持导出 live始终使用属性访问default 导入需要 interop 时生成($parcel$interopDefault(${renamed}))否则renamed.defaultESM 输出下使用命名导入同样保持 live通过getTopLevelName生成以 bundle publicId 和 specifier 为前缀的去重顶层变量名避免本地变量遮蔽。7.2 async bundle 与 bundle queue 运行时isAsyncBundle在构造函数中判定存在 JS 类型的父 bundle、环境未隔离且 bundleBehavior 不是 isolated。对 async bundle主 entry 不会被立即执行可能要等 sibling bundle 加载完成因此entries会过滤掉主 entry。shouldBundleQueue()L275-L288判断是否需要实验性的 bundle queue 运行时要求useAsyncBundleRuntime、被 HTML 引用、ESM 输出等若需要runWhenReady()会把 entry 的执行代码包装为$parcel$global.rwr(bundlePublicId, fn, [依赖bundle列表]);对应的bundleQueuePrelude定义在 helpers.js#L54 起实现等待依赖 bundle 全部加载后再执行的队列语义。7.3 条件 require 与运行时去重文档在 docs/Scopehoisting.md 中说明了为什么还需要 registry跨 bundle 复用的资产、以及if/函数内出现的条件require无法用纯 ESM 声明表达。因此拥有至少一个条件 incoming 依赖或被其他 bundle 使用的资产必须被parcelRequire.register包装包装子图内import 不能再替换为顶层变量而是替换为 CJS 等价形式var $id parcelRequire(id);然后$id.foo这样条件分支内的副作用才按运行时语义执行。同时registry 的另一个价值是运行时去重runtime deduplication当一个资产被包含进多个 bundle 时如两个 async bundle 各自内联了同一份lib通过共享$parcel$global上的注册表保证该资产最多只求值一次副作用不重复执行且instanceof/constructor等身份判断保持成立。八、InteropESM 导入 CJS 的默认导出处理Parcel 对ESM 默认导入 CommonJS遵循社区惯例文档 docs/Scopehoisting.md 的 Interop 一节同步 ESM 默认导入 CJS 时import v from ./other中v应等于该 CJS 模块的 exports namespace 对象如{ x: 2, y: 3 }但若该模块实际上是由 ESM 转译来的 CJS如 Babel/tsc 转译后发布到 npm转译器会写入exports.__esModule true;此时默认导入应指向转译后的exports.default传统的解决方式是运行时 helperinteropRequireDefault(obj)检查__esModule标志。借助静态分析symbol propagation 提供的符号信息Scope Hoisting 打包器可以在很多情况下省略这个运行时调用当导入方被静态判定为 ESM 或 ESM 转 CJS 时直接生成renamed.default或($parcel$interopDefault(...))。interop 相关的判断分散在getSymbolResolutionisDefaultInterop分支L1047-L1054、needsDefaultInterop()L1474-L1489与addExternal中需要满足*符号存在、无default符号但存在 default 导入依赖等条件。九、从文档到源码关键文件速查关注点文件Scope Hoisting Packager 主类package/buildAsset/buildReplacements/getSymbolResolution 等packages/packagers/js/src/ScopeHoistingPackager.js打包器入口、DevPackager/ScopeHoistingPackager 选择、parcelRequireName配置packages/packagers/js/src/index.jsprelude、helpers、bundle queue 运行时packages/packagers/js/src/helpers.js输出格式ESM/CJS/Globalpackages/packagers/js/src/ESMOutputFormat.js 等BundleGraph 层递归符号解析getSymbolResolutionpackages/core/core/src/BundleGraph.js#L1658符号、树摇、interop、运行时去重等前置概念docs/Scopehoisting.md十、总结Parcel 的 Scope Hoisting Packager 是生产构建中零配置高性能输出的核心引擎。本文沿着 docs/Scopehoisting Packager.md 的脉络完整还原了它的工作方式入口package()先loadAssets加载代码并判定 wrapped 集合再对每个资产执行processAsset→visitAsset→buildAssetwrapped 资产优先置于 bundle 顶部依赖通过import语句替换而非图遍历处理buildAsset()五步跳过判断 →buildReplacements构建依赖表与符号替换表 →buildAssetPrelude合成 exports 对象与$parcel$export/$parcel$exportWildcard/interop flag → 单趟REPLACEMENT_RE正则完成 import 内联、符号替换与 source map 行/列维护 → 按需parcelRequire.register包装两级符号解析Packager 层的getSymbolResolution在bundleGraph.getSymbolResolution之上叠加了 interop 判定、hoistedRequires收集与 wrapped 资产语义修正BundleGraph 层则递归穿透 re-export 链返回找到顶层变量未找到undefined未使用falsebailoutnull四种结果boundary参数保证解析在离开 bundle 时停止。理解这套机制你就能读懂 Parcel 构建产物中各种$id$export$foo、parcelRequire(id)、$parcel$interopDefault(...)标识符的来源也就能在排查产物异常、评估 bundle 体积、或为 Parcel 贡献代码时快速定位到对应实现位置。【免费下载链接】parcelThe zero configuration build tool for the web. 项目地址: https://gitcode.com/gh_mirrors/pa/parcel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考