Im vorherigen Kapitel haben wir die Positionierung des core-Repositories als engineeringtechnische Mutterbasis geklärt und wie der pnpm-Workspace und die Root-Konfiguration alle Unterpakete einheitlich einschränken. Jetzt tauchen wir in den Kern des Build-Systems ein und verfolgen, wie ein Befehl den gesamten Build-Prozess antreibt.node scripts/build.js vueerscheint einfach, ist aber der einzige Einstiegspunkt für alle Artefakte – esm-bundler, cjs, global. Zu verstehen, wie es Benutzerabsichten in ausführbare Build-Aufgaben übersetzt, ist ein entscheidender Schritt zum Verständnis des Vue-Build-Mechanismus.

Rollup-Konfigurationsgenerierung: Von Umgebungsvariablen zu Multi-Format-Artefakten

build.jsNach dem Start von Rollup überexecgeht die Kontrolle anrollup.config.jsüber. Diese Datei ist das „Gehirn“ des Build-Systems – sie liest Umgebungsvariablen und generiert dynamisch ein Array von Rollup-Konfigurationsobjekten.

Validierung von Umgebungsvariablen und Paketlokalisierung

📎 rollup.config.js:27-29

WennTARGETnicht gesetzt ist, wird direkt ein Fehler geworfen. Das ist defensives Programmieren: Die Rollup-Konfiguration könnte direkt aufgerufen werden (z. B.rollup -c), wobei keinebuild.jsUmgebungsvariablen injiziert werden, und muss schnell fehlschlagen.

📎 rollup.config.js:32-44

Hier wird die Logik zur Bestimmung privater Pakete ausbuild.jsdupliziert – weilrollup.config.jsein unabhängiger Prozess ist und den Speicherzustand vonbuild.jsnicht teilen kann.resolveDie Funktionpkglöst relative Pfade in absolute Pfade im Paketverzeichnis auf,package.jsonist der Inhalt derpackageOptionsdes Zielpakets,buildOptionsist das darin enthaltenename-Feld,buildOptions.filenameist das Präfix des Artefaktdateinamens (vorzugsweise

, andernfalls der Verzeichnisname).outputConfigs

📎 rollup.config.js:58-88

Format-Zuordnungstabelle:

• esm-bundler、esm-browser、esm-bundler-runtime、esm-browser-runtimeDiese Tabelle definiert die Zuordnung von 7 Formaten zu Ausgabekonfigurationen. Wichtige Beobachtungen:format: 'es'sind alle
• cjs, der Unterschied liegt nur im Dateinamen.format: 'cjs'。
• globalistglobal-runtimeundformat: 'iife'ist<script>(Immediately Invoked Function Expression), geeignet für die direkte Einbindung über
• runtime-Tags.vueFormate mit dem Suffix

sind nur für das Haupt-

📎 rollup.config.js:91-92

-Paket sinnvoll – sie enthalten keinen Compiler und sind kleiner.FORMATSFormat-Auswahl: Drei PrioritätsebenenbuildOptions.formatsDie Format-Auswahl folgt drei Prioritätsebenen: Kommandozeilen-['esm-bundler', 'cjs']。PROD_ONLYUmgebungsvariable > Paket-

> Standard-

📎 rollup.config.js:97-114

Die Umgebungsvariable steuert, ob die Basiskonfiguration übersprungen wird – wenn nur die Produktionsversion gebaut wird, ist das Basiskonfigurations-Array leer und es werden anschließend nur Produktionskonfigurationen eingefügt.NODE_ENV === 'production'Anhänge-Logik der Produktionskonfiguration

• WennpackageOptions.prod === false, dann für jedes Format:
• Wenncjs, überspringen (das Paket benötigt keine Produktionsversion).createProductionConfigWenn es.prod.jsist, wird
• angehängt – erzeugt die/^(global|esm-browser)(-runtime)?/-Datei.createMinifiedConfigWenn

createConfig

createConfigverwendet? Weil CJS für Node gedacht ist, die Node-Umgebung keine Komprimierung benötigt (der Benutzer kümmert sich selbst darum), aber zwischen dev/prod-Zweigen unterscheiden muss; während direkt im Browser eingebundene Artefakte komprimiert werden müssen, um die Größe zu reduzieren. Dieser Unterschied zeigt sich in der Implementierung der beiden Factory-Funktionen.

📎 rollup.config.js:125-142

: Der Kern der Konfigurationsgenerierung

• isProductionBuildist die größte Funktion; sie empfängt Format und Ausgabekonfiguration und gibt ein vollständiges Rollup-Konfigurationsobjekt zurück.__DEV__Am Anfang steht die Berechnung einer Reihe boolescher Flags:.prod.js: Bestimmt durch die
• isBundlerESMBuild、isBrowserESMBuild、isCJSBuild、isGlobalBuildUmgebungsvariable oder ob der Dateiname
• isServerRendererenthält.server-renderer。
• isCompatPackage、isCompatBuild: Bestimmt durch regulären Ausdruck auf den Formatnamen.
• isBrowserBuild: Ob der Paketname

ist: im Zusammenhang mit Vue-2-kompatiblen Builds.resolveDefine、resolveReplace、resolveExternal: Global-Build oder Browser-ESM-Build, und der Nicht-Browser-Zweig ist nicht aktiviert.

📎 rollup.config.js:144-157

Diese Flags werden später inexportswiederholt verwendet und sind die zentrale Grundlage für die Konfigurationsdifferenzierung.autoGrundeinstellungen der Ausgabekonfiguration: Banner-Copyright-Header,named-Modus (compat-Pakete verwendenesModule, die übrigenexternalLiveBindings: false), CJS-Build aktiviertreexportProtoFromExternal: false-Interoperabilität, Sourcemap wird durch Umgebungsvariablen gesteuert,output.nameundwindowsind Kompatibilitätseinstellungen von Rollup 4. Der Global-Build setzt zusätzlich

, also den Variablennamen, der an

📎 rollup.config.js:159-168

gehängt wird.src/index.tsAuswahl der EinstiegsdateiruntimeDer Standard-Einstieg istsrc/runtime.ts.compat-Paket-ESM-Build muss sowohl default als auch named exportieren, daher wird ein separateresm-index.ts / esm-runtime.tsEinstiegspunkt verwendet.

Makrodefinition:resolveDefine

📎 rollup.config.js:170-218

resolveDefineGibt eine Ersetzungstabelle zurück, die im Quellcode__COMMIT__、__VERSION__、__BROWSER__Makros durch Literale ersetzt. Diese Makros werden im Quellcode für bedingte Kompilierung verwendet – zum Beispielif (__DEV__) { ... }wird im Produktions-Build durchif (false) { ... }ersetzt und dann durch Tree-Shaking entfernt.

Schlüssendesign:__FEATURE_OPTIONS_API__、__FEATURE_PROD_DEVTOOLS__Feature-Flags wie diese bleiben imesm-bundlerBuild als__VUE_OPTIONS_API__solche Bezeichner erhalten, damit Endbenutzer sie über die Bundler-Konfiguration überschreiben können; in anderen Builds werden sie direkt hartcodiert alstrueoderfalse。

📎 rollup.config.js:203-206

Nicht-esm-bundlerBuild hartcodiert__DEV__, da ihre dev/prod-Verzweigungen zur Build-Zeit bereits feststehen.

📎 rollup.config.js:210-216

Der letzte Schritt erlaubt Umgebungsvariablen, jede Makrodefinition zu überschreiben, und unterstützt__RUNTIME_COMPILE__=true pnpm build runtime-coresolche Inline-Überschreibungen.

Ersetzungs-Plugin:resolveReplace

📎 rollup.config.js:222-255

resolveReplaceVerarbeitet außerhalb vonresolveDefineErsetzungen, die esbuild nicht verarbeiten kann:

• FührtenumDefineszusammen (ausinlineEnumsdie Inline-Enum-Definitionen).
• Im Produktions-Browser-Build wird der Fehlererstellungsfunktion eine/*@__PURE__*/Annotation hinzugefügt, um Tree-Shaking zu unterstützen.
• esm-bundlerIm__DEV__Build wird!!(process.env.NODE_ENV !== 'production')durch
• ersetzt, damit der Bundler entscheidet.process.envIm Browser-ESM-Build wird

durch ein leeres Objekt ersetzt, um Browserfehler zu vermeiden.resolveExternal

📎 rollup.config.js:257-283

Externe Abhängigkeiten:treeShakenDepsDies ist der Kern der Denkaufgabe am Ende des vorherigen Kapitels. Der Browser-Build gibt nurdependenciesals external zurück – diese Abhängigkeiten werden zwar importiert, aber im Browser-Zweig nicht tatsächlich ausgeführt; sie werden hier nur aufgeführt, um Rollup-Warnungen zu unterdrücken. Node/ESM-Bundler-Builds externalisieren allepeerDependenciesundpath、url、streamsowie Node-Built-in-Module wie

.

📎 rollup.config.js:319-352

Finales Konfigurationsobjekt

• inputDas zurückgegebene Konfigurationsobjekt enthält:
• external: Absoluter Pfad zur Einstiegsdatei.
• plugins: Liste externer Abhängigkeiten.
• output: Plugin-Array in der Reihenfolge json → alias → enumPlugin → replace → esbuild → nodePlugins.
• onwarn: Ausgabekonfiguration.CIRCULAR_DEPENDENCY: Filtert
• treeshake.moduleSideEffects: falseWarnungen heraus (im Vue-Quellcode existieren zirkuläre Abhängigkeiten, die zur Laufzeit harmlos sind).

: Teilt Rollup mit, dass alle Module keine Seiteneffekte haben, aggressives Tree-Shaking.

flowchart LR
    env["process.env<br/>TARGET, FORMATS, NODE_ENV"] --> pkg_load["require(package.json)"]
    pkg_load --> pkg_opts["packageOptions<br/>= pkg.buildOptions"]
    env --> fmt_sel["packageFormats<br/>= FORMATS || buildOptions.formats || default"]
    fmt_sel --> cfg_map["outputConfigs[format]"]
    pkg_opts --> create_cfg["createConfig(format, output)"]
    cfg_map --> create_cfg
    create_cfg --> define["resolveDefine()<br/>__DEV__, __BROWSER__ ..."]
    create_cfg --> replace["resolveReplace()<br/>enumDefines, __DEV__"]
    create_cfg --> external["resolveExternal()<br/>treeShakenDeps / deps"]
    create_cfg --> node_plugins["resolveNodePlugins()<br/>commonJS, nodeResolve"]
    define --> rollup_cfg["RollupOptions<br/>{ input, external, plugins, output }"]
    replace --> rollup_cfg
    external --> rollup_cfg
    node_plugins --> rollup_cfg
    rollup_cfg --> rollup_run["Rollup 执行构建"]
    rollup_run --> dist["dist/*.js 产物落盘"]

Kopieren

execArtefakt-Persistenz und Größenprüfung

build.jsProzessverwaltung vonexecStartet den Rollup-Unterprozess über

📎 scripts/utils.js:64-114

exec: Kapseltspawn, gibt ein Promise zurück. Schlüssendesign:

• stdioStandardmäßig ist['ignore', 'pipe', 'pipe']– stdin ignoriert, stdout/stderr als Pipe erfasst.
• shell: process.platform === 'win32'– unter Windows wird eine Shell benötigt, um Befehle korrekt aufzulösen.
• Sammelt Ausgaben überstderrChunksundstdoutChunksArrays, die imexit-Event zusammengefügt werden.
• Bei Exit-Code 0 wird resolved, andernfalls rejected mit stderr-Inhalt.

Größenprüfung:checkAllSizes

📎 scripts/build.js:206-215

Die Größenprüfung hat zwei Überspringbedingungen:devOnlyist wahr, oder es wurde ein Format angegeben, dasglobalnicht enthält. Denn die Größenprüfung gilt nur für globale Build-Artefakte – das sind Dateien, die Endbenutzer direkt einbinden, und die größenempfindlichsten.

📎 scripts/build.js:222-228

checkSizePrüft zwei Dateien:${target}.global.prod.jsund${target}.runtime.global.prod.js(letztere wird nur geprüft, wenn kein Format angegeben wurde oderglobal-runtimeangegeben wurde).

📎 scripts/build.js:235-264

checkFileSizeLiest die Datei, berechnet die komprimierte Größe mitgzipSyncundbrotliCompressSync, formatiert die Ausgabe mitprettyBytes. WennwriteSizewahr ist, werden die Ergebnisse intemp/size/${fileName}.jsongeschrieben – dies ist die Datenquelle für die Größenbudget-Prüfung in CI.

Typdeklarations-Build

📎 scripts/build.js:94-108

WennbuildTypeswahr ist, wirdpnpm run build-dtsaufgerufen und die Zielliste über--environment TARGETS:...übergeben. Dies stellt sicher, dass Typdeklarationen nur für tatsächlich gebaute Pakete generiert werden.

Design-Überlegungen und Produktions-Fallstricke

Warum--environmentstatt direkter Parameterübergabe verwenden?Rollups--environmentist die einzige Möglichkeit, in der Konfigurationsdatei überprocess.envParameter zu lesen. Direkte Übergabe von--config-Parametern erfordert Parsen vonprocess.argv, während--environmentstrukturierte Schlüssel-Wert-Paar-Analyse bietet.

fuzzyMatchTargetDie Regex-Falle von target.match(partialTarget).partialTargetInruntime-core，-istruntime.core，.Benutzereingabe. Wenn der Benutzer

eingibt, ist es ein Literal in der Regex, kein Problem; aber wenn runParalleleingegeben wird, matcht es beliebige Zeichen und könnte unerwartete Ziele treffen. Dies ist das inhärente Risiko von Fuzzy-Matching, aber Vues Paketnamen enthalten keine Regex-Sonderzeichen, sodass es praktisch nicht ausgelöst wird.cpus().lengthRessourcenkonkurrenz bei parallelen Builds.--max-old-space-sizeverwendet

scanEnumsals Parallelitätsobergrenze, aber jeder Rollup-Prozess startet selbst Worker. In CI-Containern mit wenigen Kernen kann dies zu Speicherüberlauf führen. Wenn in der Produktion OOM auftritt, kann dies durch removeCacheoder Reduzierung der Parallelität gemildert werden.finallyDer Cache-Lebenszyklus vonscanEnums.removeCachewird infinallyaufgerufen, aber wennscanEnumsselbst einen Fehler wirft, wirdtrynicht zugewiesen und der Aufruf in

resolveExternalschlägt fehl. Tatsächlich ist die vonzurückgegebene Funktion bereits vorruntime-corebestimmt, sodass dieses Risiko nicht besteht – aber dies ist ein Timing-Detail, das beim Lesen bestätigt werden muss.resolveExternalDas Auslassungsrisiko von

.

Die Denkaufgabe des vorherigen Kapitels hat bereits gezeigt: Wennnode scripts/build.js vueeine neue Abhängigkeit hinzugefügt wird, aber vergessen wird,

1. parseArgszu aktualisieren, packt der Browser-Build diese Abhängigkeit ein (da sie nicht in der external-Liste steht), was zu Größenaufblähung führt. Dies sind die inhärenten Kosten der „Whitelist-external"-Strategie.commitKapitelzusammenfassung

2. run()Eine vollständige Reise vonscanEnums:fuzzyMatchTargetparst die Kommandozeile,allTargets）。

3. buildAllwird synchron abgerufen.runParallelRuftbuild。

4. buildauf, generiert den Enum-Cache, parst das Ziel (package.jsonoderdistüber--environmentparallel geplantexecRollup starten.

5. rollup.config.jsUmgebungsvariablen lesen, übercreateConfigKonfigurationsarray generieren,resolveDefine/resolveReplace/resolveExternalMakros, Ersetzungen und externe Abhängigkeiten separat verarbeiten.

6. Rollup führt den Build aus, die Artefakte werden auf die Festplatte geschrieben nachdist/。

7. checkAllSizesgzip/brotli-Größe berechnen, optional schreiben nachtemp/size/。

8. Wenn--withTypes, aufrufenbuild-dtsTypdeklarationen generieren.

Gedanken und Selbsttest dieses Kapitels

filtert Warnungen für nicht-zyklische Abhängigkeiten heraus).scripts/dev.jsDamit haben wir die vollständige Build-Reise von der Befehlsanalyse bis zum Rollup-Aufruf durchlaufen und Kernmechanismen wie nebenläufige Planung und Filterung privater Pakete aufgedeckt. Der Produktions-Build ist jedoch nur die Hälfte der Geschichte. Im nächsten Kapitel wenden wir uns der Entwicklungszeit-Pipeline zu und sehen, wie

Verifikationsstatus: FACT-Zeilennummern echt verankertscripts/dev.jsIm vorherigen Kapitel haben wir die vollständige Kette des Produktions-Builds von der Parameteranalyse bis zum Schreiben der Multi-Format-Artefakte auf die Festplatte verfolgt; diese Kette strebt Vollständigkeit und Normkonformität der Artefakte an. Das Kernanliegen der Entwicklungszeit ist jedoch nur eines: eine Zeile Code ändern, sofort im Browser das Ergebnis sehen. Die Kette des Produktions-Builds „Parameter parsen → Konfiguration generieren → vollständiges Bündeln → auf die Festplatte schreiben" dauert oft Dutzende Sekunden und kann dieses Anliegen überhaupt nicht erfüllen. Das Vue-core-Repository unterhält dafür eine unabhängige Entwicklungszeit-Pipeline:scripts/pre-dev-sfc.jsverwendet den Watch-Modus von esbuild für inkrementelle Builds,

kompiliert den SFC-Compiler vor dem Haupt-Build. Dieses Kapitel zerlegt den Kooperationsmechanismus der beiden.

3.1 dev.js: Inkrementeller Builder mit esbuild für Geschwindigkeit

Intuitives Modell📎 scripts/dev.js:3-5

Der Produktions-Build ist wie „der offizielle Satz und Druck in einer Druckerei" – Qualität hat Priorität, etwas langsamer ist egal; der Entwicklungs-Build ist wie „eine Bleistiftskizze auf einem Notizzettel" – nicht auf Schönheit ausgerichtet, nur darauf, sofort sichtbar zu sein. Vue wählt esbuild statt Rollup, um diese Skizze zu zeichnen; der Grund steht im Kommentar am Anfang der Datei: Rollup-Artefakte sind kleiner, Tree-Shaking ist besser, aber esbuild ist viel schneller.

Ohne dieses Skript müsste der Entwickler bei jeder Änderung einen vollständigen Produktions-Build ausführen, der Feedback-Zyklus würde von Millisekunden auf Minuten degradieren, und das Hot-Update-Erlebnis wäre völlig verloren.

Parameteranalyse und Format-AbleitungparseArgsDer Skripteinstieg verwendet Nodes eingebautesformat, um drei Optionen zu parsen:global）、prod(Standardfalse）、inline(Standardfalse）。📎 scripts/dev.js:18-40Positionsargumente werden gesammelt alstargets, falls leer, dann standardmäßig['vue']。📎 scripts/dev.js:42-53

formateinen Fehler wirft.globalDie Zuordnung zum esbuild-Ausgabeformat erfolgt über drei Verzweigungen: beginnend mitiifewird zucjszugeordnet, gleichcjswird zuesm。📎 scripts/dev.js:42-53zugeordnet, alles andere einheitlich-runtimeDer Dateinamensuffix des Produkts wird dann durchglobal-runtimeSuffix separat behandelt:runtime.globalwird zu📎 scripts/dev.js:42-53

, der Rest bleibt unverändert.

Zielpaketlokalisierung und Ausgabepfadpackages-privateDas Skript liest zuerst die📎 scripts/dev.js:56Verzeichnisliste, um zu bestimmen, ob das Zielpaket zu einem öffentlichen oder privaten Paket gehört.packagesFür jedes target wird entschieden, ob der Paketbasispathpackages-privateoderrequireist, dannpackage.jsondessenversion, umbuildOptions。📎 scripts/dev.js:58-63

undvue-compatzu erhalten.vueDer Ausgabedateiname hat einen Sonderfall:vue-compat.global.js。📎 scripts/dev.js:64-69Das Ziel wird umbenannt zupackages/vue/dist/vue.global.js，prod, um zu vermeiden, dass das Produktprod.heißt. Der endgültige Pfad hat die Form

Wenn wahr, wird

externalSegment eingefügt.

external-Auflösung: Vermeidung, Abhängigkeiten ins Produkt zu packeninlineDascjsArray bestimmt, welche Module nicht gebündelt werden. Die Logik ist zweischichtig:esm-bundlerErste Schicht: Wenndependencies、peerDependenciesnicht aktiviert ist und das Formatpath、url、streamist oder📎 scripts/dev.js:76-88enthält, werden alle Schlüssel von@vue/compiler-sfczu external hinzugefügt undserver-rendererdrei Node-Built-in-Module hartcodiert.

Der Kommentar erklärt explizit, dass diese drei fürcompiler-sfcund@vue/consolidatevorbereitet sind.devDependenciesZweite Schicht: Für dasfs、vm、cryptoZiel werden zusätzlich📎 scripts/dev.js:90-112vonreact-dom/server、teacup/lib/express、arc-templates/dist/es5、then-pug、then-jadeaufgelöst, diese sowie

Diese Logik ist hochgradig redundant mit

, was auch im Quellcode-Kommentar zugegeben wird (log-rebuild). Der Grund, warum keine gemeinsame Funktion extrahiert wurde, ist, dass es feine Unterschiede in der external-Strategie zwischen dev und prod gibt (dev externalisiert aggressiver, um Builds zu beschleunigen), und eine erzwungene Vereinheitlichung würde die Kopplung erhöhen.onEndPlugins und define-Injektion📎 scripts/dev.js:115-124Das Plugin-Array hat standardmäßig nur ein

definedes Pakets wahr ist, wird📎 scripts/dev.js:141-159eingehängt.__XXX__Solche Pakete (wie

• __COMMIT__) durchlaufen im Browser-Build immer noch den Node-Zweig und benötigen Polyfills für Node-Built-in-Module, um in der Browser-Umgebung zu funktionieren."dev"，__VERSION__Der
• __DEV__Block ist der informationsdichteste Teil dieses Kapitels.prodEr ersetzt alle__TEST__Makros im Quellcode durch Literale:false；
• __BROWSER__ist fest aufformat !== 'cjs' && !pkg.buildOptions?.enableNonBrowserBranches。📎 scripts/dev.js:146-148gesetzt,
• __SSR__nimmt die Paketversion;format !== 'global'wird durch das
• __COMPAT__Flag bestimmt,vue-compatist konstant
• Die Ableitung von__FEATURE_SUSPENSE__、__FEATURE_OPTIONS_API__、__FEATURE_PROD_DEVTOOLS__、__FEATURE_PROD_HYDRATION_MISMATCH_DETAILS__ist am subtilsten:

Das heißt, nur „nicht cjs und Paket unterstützt keinen Nicht-Browser-Zweig" wird als Browser-Umgebung markiert;vitest.config.tsistdefine, d.h. der global-Build aktiviert den SSR-Zweig nicht;📎 vitest.config.ts:6-21wird dadurch bestimmt, ob das target__TEST__ist;true、__DEV__Drei Feature-Flags (true) sind im dev-Modus alle fest verdrahtet.

Diese Makros entsprechen eins zu eins dem

Block inesbuild.context(...).then(ctx => ctx.watch())。📎 scripts/dev.js:130-161 context.watch()Die Testumgebung setztonEndauf

flowchart TD
    start["parseArgs 解析 format/prod/inline"] --> targets{"positionals 为空?"}
    targets -->|是| def["targets = ['vue']"]
    targets -->|否| use["targets = positionals"]
    def --> loop["遍历每个 target"]
    use --> loop
    loop --> priv{"target 在 packages-private?"}
    priv -->|是| pbase["pkgBase = packages-private"]
    priv -->|否| pub["pkgBase = packages"]
    pbase --> req["require package.json"]
    pub --> req
    req --> ext{"inline 开启?"}
    ext -->|是| noext["external = []"]
    ext -->|否| fmt{"format 是 cjs 或 esm-bundler?"}
    fmt -->|是| deps["加入 dependencies/peerDependencies + path/url/stream"]
    fmt -->|否| sfc{"target == compiler-sfc?"}
    deps --> sfc
    sfc -->|是| cons["加入 consolidate devDeps + fs/vm/crypto"]
    sfc -->|否| noext
    cons --> ctx["esbuild.context 创建上下文"]
    noext --> ctx
    ctx --> watch["ctx.watch() 启动监听"]
    watch --> onend["onEnd 打印 built: 相对路径"]

auf

. Der Unterschied zum dev-Build ist genau der Unterscheidungspunkt zwischen den beiden Laufzeitzuständen „Test vs. Entwicklung".

watch-Modus-Startcompiler-sfcDer letzte Schritt ist, dasscompiler-coreeinen Build-Kontext erstellt, aber nicht sofort ausführt,compiler-coreerst dann wird die Dateiüberwachung tatsächlich gestartet. Danach pflegt esbuild intern den Abhängigkeitsgraphen; jede Änderung an einer abhängigen Datei löst einen inkrementellen Rebuild aus, und der Rebuild-Abschluss-Callbackcompiler-sfcgibt das Log aus..vueKopierenpre-dev-sfc.js3.2 pre-dev-sfc.js: Der Precompile-Wächter zur Auflösung zirkulärer Abhängigkeiten

Intuitives Modell

Stellen Sie sich ein „Henne-Ei"-Dilemma vor:compiler-sfc、compiler-core、compiler-dom、compiler-ssr、shared。📎 scripts/pre-dev-sfc.js:4-10Der Quellcode vonpackages/${pkg}/dist/${pkg}.cjs.jsimportiert📎 scripts/pre-dev-sfc.js:4-23

, undallFilesPresentbenötigt im Entwicklungszustandfalse, umbreakDateien zu verarbeiten. Wenn beide auf esbuild watch in Echtzeit kompilieren angewiesen sind, blockiert derjenige, der zuerst kompiliert.📎 scripts/pre-dev-sfc.js:20-21Die Rolle vonallFilesPresentist „zuerst das Ei ausbrüten, dann das Huhn aufziehen" – vor dem Start des Haupt-Builds sicherstellen, dass die CJS-Produkte dieser Pakete bereits existieren.process.exit(1)Checkliste und Kurzschlusslogik📎 scripts/pre-dev-sfc.js:25-27

Das Skript pflegt eine feste Liste:

Für jedes Paket wird geprüft, obexit(1)existiert.&&Sobald eines fehlt, wird

flowchart TD
    start["遍历 packagesToCheck 清单"] --> check{"dist/pkg.cjs.js 存在?"}
    check -->|是| next{"还有下一个包?"}
    next -->|是| check
    next -->|否| ok["allFilesPresent 保持 true"]
    check -->|否| fail["allFilesPresent = false 并 break"]
    ok --> exit0["正常退出 退出码 0"]
    fail --> exit1["process.exit(1) 退出码 1"]

gesetzt und sofort

scripts/dev.js, ohne die restlichen Pakete zu prüfen.scripts/aliases.jsWenn schließlich📎 scripts/aliases.js:7-7

falsch ist,

resolveEntryForPkgwird mit einem Nicht-Null-Code beendet.packages/${p}/src/index.ts。📎 scripts/aliases.js:7-7Semantik des Exit-Codesvue、vue/compiler-sfc、vue/server-renderer、@vue/compat。📎 scripts/aliases.js:16-21

Dieses Skript führt selbst keine Kompilierung durch, es macht nur „Existenz-Assertions".packagesEs ist ein Signal für den aufrufenden Layer (normalerweise dievue-Kette des npm-Skripts oder CI-Skripte): Die Produkte sind unvollständig, es muss zuerst ein vollständiger Build ausgeführt werden. Wenn alle existieren, wird normal beendet (Exit-Code 0), und der Haupt-Build fährt fort.nonSrcPackages（sfc-playground、template-explorer、dts-testKopieren@vue/${dir}3.3 aliases.js und vitest.config.ts: Die andere Hälfte der Entwicklungskette📎 scripts/aliases.js:23-35

vitest's define und Alias-Konsum

vitest.config.tsdirekt importentriesalsresolve.alias。📎 vitest.config.ts:3📎 vitest.config.ts:22-24dessendefineBlock steht im Kontrast zur Makro-Injektion von dev.js: Testumgebung__DEV__: true、__TEST__: true、__BROWSER__: false、__CJS__: true。📎 vitest.config.ts:6-21

Die Tests sind in fünf Projekte aufgeteilt:unit、unit-gc、unit-jsdom、e2e、e2e-browser。📎 vitest.config.ts:51-118wobeiunit-gcverwendetpool: 'forks'und übergibt--expose-gc, um speziell SSR-Tests auszuführen, die manuell GC auslösen müssen.📎 vitest.config.ts:65-76 e2e-browserhingegen aktiviert die Chromium-Instanz von Playwright, um Transition-bezogene Tests auszuführen.📎 vitest.config.ts:99-117

sequenceDiagram
    participant Dev as 开发者
    participant NPM as npm script
    participant Pre as pre-dev-sfc.js
    participant DevJS as dev.js
    participant ESB as esbuild context
    participant FS as 文件系统

    Dev->>NPM: 启动开发
    NPM->>Pre: 检查 SFC 产物
    Pre->>FS: existsSync(dist/*.cjs.js)
    alt 产物缺失
        FS-->>Pre: false
        Pre-->>NPM: exit(1)
        NPM-->>Dev: 提示先跑完整构建
    else 产物齐全
        FS-->>Pre: true
        Pre-->>NPM: exit(0)
        NPM->>DevJS: 启动 dev.js
        DevJS->>ESB: context(...).watch()
        ESB->>FS: 监听源码变化
        Dev->>FS: 修改 src/index.ts
        FS-->>ESB: 文件变更事件
        ESB->>ESB: 增量重建
        ESB-->>Dev: onEnd 打印 built: 路径
    end

Designüberlegungen

Warum verwendet dev esbuild und prod Rollup?Dies ist keine willkürliche Technologiewahl, sondern die Einschränkungen der beiden Szenarien unterscheiden sich. Im Entwicklungsmodus ist die Artefaktgröße unkritisch, die Feedback-Latenz jedoch äußerst kritisch; im Produktionsmodus ist es umgekehrt. esbuild ist in Go geschrieben und hochgradig parallelisiert, Kaltstart und inkrementelle Builds sind um eine Größenordnung schneller, aber seine Tree-Shaking- und Code-Splitting-Fähigkeiten sind schwächer als die von Rollup.📎 scripts/dev.js:3-5Zwei Werkzeuge für zwei Szenarien einzusetzen, ist ein pragmatischer Kompromiss im Engineering.

Ist die Duplizierung der external-Liste technische Schuld?Die external-Logik von dev.js und rollup.config.js ist dupliziert, was auch in den Quellcode-Kommentaren zugegeben wird.📎 scripts/dev.js:73Aber die external-Mengen der beiden sind nicht vollständig identisch – dev externalisiert aggressiver für Geschwindigkeit. Eine gewaltsame Extraktion in eine gemeinsame Funktion würde einen parametrisierten Differenz-Schalter erfordern, was beide Logiken schwerer lesbar machen würde. Dies ist ein typischer Kompromiss von „Duplizierung ist besser als falsche Abstraktion".

Kapitelzusammenfassung

Dieses Kapitel hat die drei Puzzleteile der Vue-Core-Entwicklungsmodus-Kette auseinandergenommen:

1. scripts/dev.js: Inkrementelle Builds mit esbuild'scontext().watch()implementieren, durchparseArgsFormat und Flags auflösen, dynamischrequireZielpaketpackage.jsonAusgabepfad lokalisieren, Makros wie__DEV__、__BROWSER__injizieren, um bedingte Kompilierung zu steuern, und mit demlog-rebuildPlugin nach jedem Rebuild Feedback ausgeben.

2. scripts/pre-dev-sfc.js: Vor dem Haupt-Build prüfen, ob die CJS-Artefakte der fünf Kernpakete existieren; bei Fehlen mit Exit-Code 1 kurzschließen, um Build-Deadlocks durch zirkuläre Abhängigkeiten zu vermeiden.

3. scripts/aliases.js + vitest.config.ts: Gemeinsame Pfad-Aliase für die Testkette bereitstellen, spezielle Einträge hartcodiert plus dynamisches Scannen allgemeiner Einträge, kombiniert mit Multi-Projekt-Konfiguration, die fünf Test-Szenarien abdeckt: Unit, GC, jsdom, e2e, Browser-e2e.

Kapitel-Überlegungen und Selbsttest

Die Grenzen der Zusammenarbeit der drei sind klar:pre-dev-sfcregelt „ob das Artefakt bereit ist",dev.jsregelt „wie das Artefakt schnell aktualisiert wird",aliasesregelt „wie Tests den Quellcode auflösen". Die Entwicklungskette löst das Geschwindigkeitsproblem, aber zur Build-Zeit gibt es noch eine andere, verstecktere Optimierung – Transformationen, die abgeschlossen sind, bevor der Code vom Browser ausgeführt wird. Das nächste Kapitel betritt die Compile-Zeit-Magie und zeigt, wie Enum-Inlining und Tree-shaking-Verifikationsmechanismen zur Build-Zeit TypeScript-Enums durch Literale ersetzen und sicherstellen, dass das Versprechen des bedarfsgerechten Imports nicht gebrochen wird.

Im vorherigen Kapitel haben wir gesehen, wie die Entwicklungskette durch Dateiüberwachung und inkrementelle Builds die Geschwindigkeit von „eine Zeile ändern, sofort wirksam" erreicht. Aber jenseits der Geschwindigkeit gibt es bei Vue eine verstecktere Einschränkung: Die Größe des veröffentlichten Artefakts muss kontrollierbar sein. Einer der Feinde dieser Einschränkung ist das TypeScript-Enum – es ist zur Laufzeit ein real existierendes Objekt und zerstört Tree-shaking. Dieses Kapitel betritt die Compile-Zeit und zeigt, wie scripts/inline-enums.js Enums in Literale „auflöst", bevor der Code vom Browser ausgeführt wird; und wie scripts/verify-treeshaking.js nach dem Build mithilfe von Artefakt-Strings rückwärts verifiziert, dass das Versprechen des bedarfsgerechten Imports nicht stillschweigend gebrochen wurde.

4.1 Enum-Inlining: Laufzeitobjekte in Literale auflösen

Intuitives Modell

Stell dir vor, du schreibst ein Rezept, in dem wiederholt „eine Prise Salz" vorkommt. Wenn du bei jedem Kochen zum Anhang blättern müsstest, um „eine Prise = 3 Gramm" nachzuschlagen, wäre das langsam und platzraubend. Enum-Inlining ersetzt vor dem Drucken im gesamten Buch „eine Prise Salz" direkt durch „3 Gramm Salz" und reißt dann die Anhangsseite heraus. Für den Leser (die Laufzeit) ist das Ergebnis völlig identisch, aber das Buch ist dünner.

Welche Katastrophe droht dem System ohne es? Ein normales TypeScript-enumgeneriert nach der Kompilierung ein echtes Objektliteral mit bidirektionalem Mapping (Enum[Enum.A] === 'A'). Dieses Objekt ist einemodulweite Deklaration mit Seiteneffekten, Rollup kann nicht beweisen, dass es ungenutzt ist, und muss es daher behalten – selbst wenn du nur ein Mitglied importierst, werden das gesamte Enum-Objekt samt Rückwärts-Mapping ins Artefakt eingefügt.📎 scripts/inline-enums.js:3-9Der Kommentar inconst enumsagt es deutlich: Sie verwendeten einst

, wechselten aber wegen Issue #1228 zu normalen Enums und nutzen dieses Skript, um „den Nullkosten-Vorteil von const enum manuell zurückzugewinnen".

Datenstruktur und Speicherlayout📎 scripts/inline-enums.js:33-36

• EnumMember：{ name, value }Der Kern des Skripts sind drei Typdefinitionen; wer sie versteht, versteht den gesamten Datenfluss.
• EnumDeclaration：{ id, range: [start, end], members }。range, der Name eines einzelnen Enum-Mitglieds und das ausgewertete Literal.ist derQuellcode-Byte-Offsetexport enum X { ... }, der auf die Start- und Endposition der gesamten Deklaration von
• EnumData：{ declarations, defines }。declarationsin der Datei zeigt – dies ist der Anker für die spätere präzise Ersetzung durch MagicString.defineswird nach Dateipfad indexiert und zeichnet die Ersetzungsbereiche aller Enum-Deklarationen in dieser Datei auf; ist ein flaches Mapping, dessen Schlüssel ` 形式的字符串，值是 ${Enum-Name}.${Mitgliedsname}

JSON.stringify` ist das Literal danach.definesHier gibt es ein entscheidendes Design:Der Schlüssel von。📎 scripts/inline-enums.js:98-103enthält keinen DateipfadErrorCodesDer Kommentar erklärt den Grund –@vue/compiler-corekann gleichzeitig in@vue/runtime-coreundErrorCodes.__EXTEND_POINT__existieren, daher sind gleichnamige Enums über Dateien hinweg erlaubt; aber derselbefullKey in definesdarf nicht in zwei gleichnamigen Enums wiederholt werden, sonst greiftname conflictund wirft direkt

. Dies ist eine Einschränkung „global eindeutig pro Mitgliedsname", nicht „global eindeutig pro Enum-Name".temp/enum.json。📎 scripts/inline-enums.js:33-36Der Cache liegt inscanEnums()Warum muss er auf die Festplatte geschrieben werden? Weilam Build-Eingang nur einmal aufgerufen wird, während Rollup für jedes Paket und jedes Format。📎 scripts/inline-enums.js:39-41unabhängige ProzesseinlineEnums()startet. Der Kommentar weist darauf hin: Die Daten müssen über gleichzeitige Rollup-Prozesse hinweg geteilt werden, daher müssen sie auf die Festplatte serialisiert und von den

der einzelnen Prozesse zurückgelesen werden.

Schritt für Schritt: Von grep zur Literal-Ersetzungexport enumErster Schritt: Alle Dateien mit📎 scripts/inline-enums.js:51-61per grep finden.spawnSync('git', ['grep', 'export enum'])verwendetpath:line:content, die Ausgabe hat die Form:, dann wird nachSetdas erste Segment (Dateipfad) abgetrennt und mitgit grepanstatt das Dateisystem zu durchlaufen – es scannt natürlicherweise nur die von Git verfolgten Dateien und schließt automatischnode_modulesund Build-Artefakte aus.

Zweiter Schritt: Babel parst und sammelt Enum-Informationen.📎 scripts/inline-enums.js:64-70Für jede Datei wird@babel/parsermittypescriptPlugin,sourceType: 'module'zu einem AST geparst und dann nur dieast.program.bodyTop-Level-Knoten durchlaufen.📎 scripts/inline-enums.js:74-79Es werden nurExportNamedDeclarationund derendeclaration.type === 'TSEnumDeclaration'Knoten erkannt – das heißt,nicht-exportierte enums werden nicht verarbeitet.。

Für jede Enum-Deklaration wertet das Skript jedes Mitglied einzeln aus. Die Mitgliedsauswertung hat drei Pfade:

1. Literal-Initialisierung：StringLiteraloderNumericLiteraldirektinit.value。📎 scripts/inline-enums.js:114-119

2. Binärer Ausdruck: wie1 << 2. RekursivresolveValuewerden linke und rechte Operanden verarbeitet; Operanden können Literale sein oderMemberExpression(d. h. Verweise auf zuvor definierte Enum-Mitglieder).📎 scripts/inline-enums.js:121-151Der Schlüssel liegt imMemberExpressionZweig: Er verwendetcontent.slice(node.start, node.end)ausdem ursprünglichen Quelltext, um den Ausdrucksstring herauszuschneiden (wieErrorCodes.FOO), und schlägt danndefinesnach. Wenn nichts gefunden wird, wirdunhandled enum initialization expression。📎 scripts/inline-enums.js:132-141geworfen. Das erklärt, warumdefineseine globale flache Zuordnung sein muss – bei enum-übergreifenden Verweisen kann das referenzierte Element aus einer anderen Datei stammen, aber der Schlüssel erkennt nur枚举名.成员名。

3. Unärer Ausdruck: wie-1, zusammengesetzt zum-1String und dann mitevaluateausgewertet.📎 scripts/inline-enums.js:152-163

Die Auswertung selbst verwendetnew Function('return ' + exp)()。📎 scripts/inline-enums.js:39-41Dies ist einkontrolliertes eval: Die Eingabe stammt aus bereits geparsten AST-Fragmenten im Quelltext, nicht aus beliebiger Benutzereingabe, daher ist die Sicherheitsgrenze kontrollierbar.

Dritter Schritt: Verarbeitung von Mitgliedern ohne Initialisierer (Auto-Inkrement-Semantik).📎 scripts/inline-enums.js:171-183Wenn ein Mitglied keininitializerhat: Das erste Mitglied ist standardmäßig0; wenn bei nachfolgenden MitgliedernlastInitializedeine Zahl ist, dann++; wenn es ein String ist, wirdwrong enum initialization sequencegeworfen – denn String-Enum-Mitglieder erlauben kein implizites Auto-Inkrement. Genau das ist die Semantik von TypeScript enums.

Vierter Schritt: Cache schreiben und eine Cleanup-Funktion zurückgeben.📎 scripts/inline-enums.js:200-213 scanEnums()Es wird eine Closure zurückgegeben; beim Aufruf wirdrmSyncdie Cache-Datei gelöscht.build.jsSie wird intry/finallyverwendet.📎 scripts/build.js:81-112Dies stellt sicher, dass der Cache auch dann bereinigt wird, wenn während des Builds ein Fehler geworfen wird, und den nächsten Build nicht verunreinigt.

Fünfter Schritt: Ersetzung in der Rollup-transform-Phase. inlineEnums()Der Cache wird zurückgelesen und ein Rollup-Plugin konstruiert.📎 scripts/inline-enums.js:219-234Intransform(code, id), wennidaufenumData.declarationstrifft, wird MagicString verwendet, um[start, end]diese Deklaration durch ein Objektliteral zu ersetzen.📎 scripts/inline-enums.js:242-274

Die ersetzte Form istexport const X = { ... }. Beachten Sie, dass esnicht einfach das enum löscht, sondern es in ein Objektliteral umschreibt und für numerische Mitglieder zusätzlich Reverse-Mappings erzeugt:JSON.stringify(value.toString()) + ': ' + JSON.stringify(name)。📎 scripts/inline-enums.js:257-270Der Kommentar verweist auf die reverse-mappings-Regel der offiziellen TypeScript-Dokumentation: String-Enum-Mitglieder erzeugen keine Reverse-Mappings, numerische Mitglieder schon. Dies stellt sicher, dass das Laufzeitverhalten nach der Ersetzung vollständig mit dem ursprünglichen enum übereinstimmt.

Und was den Laufzeit-Overhead wirklich beseitigt, istdefineswird an@rollup/plugin-replace。📎 rollup.config.js:222-223übergeben. AlleX.MemberReferenzenaufwerden im Ersetzungs-Plugin direkt durch Literale ersetzt, sodass das umgeschriebene Objektliteral, wenn es niemand verwendet, durch Tree-shaking entfernt werden kann.

Das folgende Flussdiagramm zeigt den vollständigen Entscheidungspfad von grep bis zur Ersetzung:

flowchart TD
    grep["spawnSync git grep 'export enum'"] --> files["去重得到文件列表"]
    files --> parse["@babel/parser 解析 AST"]
    parse --> check{"顶层节点是<br/>ExportNamedDeclaration<br/>且 declaration 为 TSEnumDeclaration?"}
    check -->|否| skip["跳过该节点"]
    check -->|是| dup{"enumIds 已含该 id?"}
    dup -->|是| err1["throw 不支持声明合并"]
    dup -->|否| member["遍历 members 求值"]
    member --> init{"有 initializer?"}
    init -->|有| eval["字面量/二元/一元求值"]
    init -->|无| auto["lastInitialized 自增或默认 0"]
    eval --> conflict{"fullKey 已在 defines?"}
    auto --> conflict
    conflict -->|是| err2["throw name conflict"]
    conflict -->|否| save["saveValue 写入 members 与 defines"]
    save --> cache["writeFileSync temp/enum.json"]
    cache --> transform["Rollup transform: MagicString 重写声明"]
    transform --> replace["plugin-replace 用 defines 替换引用"]

Designüberlegungen und Stolperfallen

Warum MagicString statt die gesamte Datei neu zu generieren?Weils.update(start, end, ...)nur den Abschnitt der Enum-Deklaration ersetzt und die übrigen Quelltextbytes vollständig unverändert bleiben,s.generateMap()und außerdem präzise Sourcemaps erzeugen kann.📎 scripts/inline-enums.js:277-281Wenn Babel den gesamten AST neu ausgeben würde, gingen ursprüngliche Formatierung und Kommentare verloren, und die Sourcemap-Qualität würde sinken.

rangeWarumnode.start/node.endstattdeclaration.start？📎 scripts/inline-enums.js:189-193behauptet wirdnode.start(d. h.ExportNamedDeclarationKnoten), deckt der Ersetzungsbereichexport enum X {...}den gesamten Abschnitt ab, einschließlichexportSchlüsselwort. Der Ersetzungstext beginnt mitexport constund schließt direkt an.

Stolperfallen:definesDie globale Eindeutigkeitsbeschränkung vonWenn es in zwei verschiedenen Dateien jeweils einErrorCodesgibt und beide__EXTEND_POINT__definieren, schlägt der Build direkt fehl.📎 scripts/inline-enums.js:101-103Das ist kein Bug, sondern bewusstes Design – weildefineseine globale Ersetzungstabelle ist und nicht zwischen Dateiquellen unterscheiden kann. Wenn in der Produktionsumgebung neue Enum-Mitglieder hinzugefügt werden und der Name mit einem vorhandenen Enum-Mitglied kollidiert, fliegt es hier auf.

Stolperfalle:new FunctionDer Auswertungszeitpunkt vonDie Auswertung binärer Ausdrücke erfolgt in derscanEnumsPhase; zu diesem Zeitpunkt ist das referenzierte Mitglied möglicherweise noch nicht indefines(wenn die Referenzreihenfolge vertauscht ist).📎 scripts/inline-enums.js:136-140wirdunhandled enum initialization expressiongeworfen. Dies erfordert, dass Verweise auf Enum-Mitglieder der Quelltextreihenfolge „erst definieren, dann referenzieren“ folgen müssen.

4.2 Tree-shaking-Verifikation: Das Versprechen anhand von Artefakt-Strings rückwirkend beweisen

Intuitives Modell

Enum-Inlining ist eine „Vorab-Optimierung“, aber greift die Optimierung wirklich? Wenn ein Helper aufgrund unsachgemäßer Schreibweise versehentlich beibehalten wird, wächst die Größe still und heimlich, ohne dass der Entwickler es bemerkt.verify-treeshaking.jsist genau dieser „nachträgliche Qualitätsprüfer“: Es baut das Artefakt und prüft dann wie bei einer Autopsie, ob im ArtefaktDinge auftauchen, die nicht auftauchen sollten. Ohne es könnte das On-Demand-Import-Versprechen von Vue nach einem Refactoring stillschweigend brechen, bis Benutzer sich über größere Pakete beschweren.

Datenstruktur und Prüfelemente

Dieses Skript hat keine komplexe Datenstruktur; der Kern ist einerrorsArray und dreiincludesPrüfungen.📎 scripts/verify-treeshaking.js:6-6Es baut zuerstglobal-runtimeFormat und liest dann jeweils die dev- und prod-Artefakte.

Die drei Prüfelemente entsprechen drei Arten von „Tree-shaking-Fehlern“:

1. dev-Artefakt enthält__spreadValues。📎 scripts/verify-treeshaking.js:13-19Dies ist der von esbuild für{ ...obj }Objekt-Spread-Syntax generierte Helper. Wenn er auftaucht, bedeutet das, dass im Laufzeitcode Objekt-Spread verwendet wurde, während Vue vereinbarungsgemäßextendHelper verwenden sollte, um zusätzlichen Code zu vermeiden.

2. prod-Artefakt enthältVue warn。📎 scripts/verify-treeshaking.js:26-31bedeutet, dass eswarn()Aufrufe gibt, die nicht durch__DEV__Bedingungen umschlossen sind, sodass Warncode in das Produktionspaket gelangt.

3. prod-Artefakt enthält DOM-Tag-Konfigurationslisten。📎 scripts/verify-treeshaking.js:33-42wiehtml,body,base、svg,animate,animateMotion、annotation,annotation-xml,maction. Diese sindisHTMLTag()Daten innerhalb von Helfern wie `helper`, die eigentlich nur im Compiler existieren sollten und von der Runtime wegoptimiert werden. Wenn sie im Runtime-Artefakt auftauchen, bedeutet das, dass der Runtime-Pfad fälschlicherweise compiler-exklusive Helper verwendet.

Step-by-Step: Validierungsablauf

📎 scripts/verify-treeshaking.js:5-5Zuerstexec('pnpm', ['build', 'vue', '-f', 'global-runtime']), nur bauenvuedes Paketsglobal-runtimeFormat – dies ist das minimalste Runtime-Artefakt und am besten geeignet, um Leaks aufzudecken. Nach dem Build werden beide Dateien synchron gelesen, einzelnincludesgeprüft, bei Treffer wird inerrorseine Nachricht mit Erklärung gepusht. Wenn schließlicherrors.lengthungleich null ist, wird ein aggregierter Fehler geworfen.📎 scripts/verify-treeshaking.js:44-48

flowchart TD
    build["exec pnpm build vue -f global-runtime"] --> readDev["读取 vue.runtime.global.js"]
    readDev --> c1{"dev 含 __spreadValues?"}
    c1 -->|是| e1["push: 应改用 extend helper"]
    c1 -->|否| readProd["读取 vue.runtime.global.prod.js"]
    e1 --> readProd
    readProd --> c2{"prod 含 'Vue warn'?"}
    c2 -->|是| e2["push: warn 未被 __DEV__ 包裹"]
    c2 -->|否| c3{"prod 含 DOM tag 配置?"}
    e2 --> c3
    c3 -->|是| e3["push: 编译器 helper 泄漏到运行时"]
    c3 -->|否| done{"errors 为空?"}
    e3 --> done
    done -->|是| pass["验证通过"]
    done -->|否| fail["throw 聚合错误"]

Designüberlegungen und Stolperfallen

4.3 Zusammenarbeit mit Rollup: Plugin-Reihenfolge und define-Injektion

Enum-Inlining läuft nicht isoliert, sondern ist in die Rollup-Plugin-Pipeline eingebettet. Um zu verstehen, warumdefinesanreplaceübergeben werden muss und nichtesbuild。

📎 rollup.config.js:47-50im Konfigurationsmodul auf oberster Ebene aufgerufen wirdinlineEnums(), muss man den Kontext verstehen: Es wird[enumPlugin, enumDefines]bei jedem Rollup-Prozessstartausgeführt und liest den vongeschriebenen Cache.scanEnumsDie Reihenfolge des Plugin-Arrays ist:

steht vorjson → alias → enumPlugin → ...resolveReplace() → esbuild。📎 rollup.config.js:324-339 enumPlugin, was bedeutet, dass das Umschreiben der Enum-Deklarationen zuerst erfolgt, dannreplaceerst mitreplacedie Referenzen ersetzt. Unddefinessteht am Ende und ist für die TS-Transpilierung zuständig.esbuildWarum

überdefinesund nicht überreplaceläuftesbuild, gibt derdefine？📎 rollup.config.js:220-221-Kommentar die Antwort: esbuilds define „ist etwas streng, erlaubt nur literales JSON oder Bezeichner". Enum-Member-Namen wieErrorCodes.__EXTEND_POINT__sind Member-Ausdrücke mit Punkt, und esbuilds define kann solche Schlüssel nicht direkt verarbeiten. Daher muss@rollup/plugin-replaceverwendet werden, das die Ersetzung beliebiger String-Schlüssel unterstützt.📎 rollup.config.js:250-251und setztpreventAssignment: true, um zu vermeiden, dass auch die linke Seite von Zuweisungsanweisungen ersetzt wird.

resolveReplace()Inconst replacements = { ...enumDefines }ist📎 rollup.config.js:222-223der erste Schritt./*@__PURE__*/Danach werden erst die Produktions-__DEV__-Annotationen,

usw. ersetzt. Diese Reihenfolge stellt sicher, dass die Enum-Literal-Ersetzung immer wirksam ist.

DesignüberlegungenDas Wesen des Enum-Inlinings ist „Build-Zeit-Komplexität gegen Runtime-Volumen tauschen".scanEnumsEs reproduziert die TypeScript-Typsystem-Semantik (Enum-Auswertung, Auto-Inkrement, Reverse-Mapping) vollständig zur Build-Zeit –📎 scripts/inline-enums.js:110-183die Auswertungslogik inunhandledist fast eine Teilmenge der Enum-Auswertung des TS-Compilers.

Validierungsskript und Inline-Skript sind ein Paar aus „Versprechen und Einlösung". scanEnumsDas Inline-Skript verspricht „Enums belegen kein Runtime-Volumen", das Validierungsskript prüft „anderer Code belegt auch nicht heimlich Volumen". Beide zusammen schützen das Volumenbudget von Vue. Dieses paarweise Design aus „Optimierung + Validierung" ist ein typisches Muster der Engineering-Praxis großer Frontend-Bibliotheken: Jede Optimierung benötigt eine automatisierte Prüfung, um Regressionen zu verhindern.inlineEnumsProzessübergreifender Cache ist ein Muss für parallele Builds.📎 scripts/inline-enums.js:39-41Das Muster „einmal ausführen,

mehrfach lesen" löst das Problem „einmal scannen, N Prozesse konsumieren". Ohne Cache müsste jeder Rollup-Prozess erneut grep + parsen, was massiv IO und CPU verschwendet.

Kapitelzusammenfassung

Enum-Inlining löst „wie man Laufzeit-Overhead zur Build-Zeit eliminiert", das Verifikationsskript löst „wie man bestätigt, dass die Optimierung nicht beschädigt wurde". Aber Build-Artefakte umfassen neben JS noch eine weitere Art von Artefakten, die ebenfalls Pipeline-Verarbeitung benötigen——Typdeklarationsdateien. Das nächste Kapitel betritt die Typartefakt-Pipeline und schaut, wie Vue aus dem Quellcode.d.tsein release-taugliches Typ-Paket generiert und wiedts-testmit Typ-Contract-Tests die Typform der öffentlichen API absichert.

Dieses Kapitel hat zwei Schlüsselskripte der Kompilierungsphase zerlegt. inline-enums.js lokalisiert Enums mit git grep, parst den AST mit Babel, wertet Member mit new Function aus, schreibt Deklarationen präzise mit MagicString um und verwandelt schließlich Enum-Referenzen über die defines-Globalersetzungstabelle in Literale, sodass das Enum-Objekt von Tree-shaking entfernt werden kann. verify-treeshaking.js prüft hingegen nach dem Build das Artefakt mit String-Sentinels, um sicherzustellen, dass drei bekannte Arten von Tree-shaking-Leaks nicht zurückkehren. Beide——einer für „Optimierung", einer für „Verifikation, dass die Optimierung nicht beschädigt wurde"——schützen gemeinsam das Größenversprechen von Vue. Als Nächstes wenden wir uns von der Kompilierungsphase dem Generierungsweg der Typartefakte zu und schauen, wie Vue sicherstellt, dass Quellcode-Typen und Release-Typen strikt übereinstimmen.

Im vorherigen Kapitel haben wirinline-enums.jsundverify-treeshaking.jszerlegt: Eines ersetzt Enum-Referenzen durch Literale, damit das Enum-Objekt entfernt werden kann, das andere bestätigt nach dem Build mit String-Sentinels, dass drei bekannte Leaks nicht zurückkehren. Beide schützen gemeinsam das Laufzeit-Größenversprechen von Vue. Aber Build-Artefakte sind nicht nur JS. Wenn der Nutzerimport { ref } from 'vue', hängen die vom Editor angezeigten Typ-Hinweise undtscdie Typprüfung des Nutzercodes alle von einer anderen Art von Artefakten ab——.d.tsDeklarationsdateien. Ist das JS-Artefakt falsch, gibt es Laufzeitfehler; ist das Typartefakt falsch, gibt es auf Nutzerseite bereits zur Kompilierungszeit Fehler, oder schlimmer: Typen driften stillschweigend, Nutzercode kompiliert durch, aber die Typform stimmt nicht mit dem tatsächlichen Laufzeitverhalten überein. Dieses Kapitel verfolgt, wie Vue die in den einzelnen Unterpaketensrcverstreuten Quellcode-Typen zu einem release-tauglichen Typ-Paket aggregiert und mitdts-built-testTyp-Smoke-Tests auf echten Build-Artefakten durchführt.

5.1 Zweistufige Typ-Pipeline: tsc liefert, rollup aggregiert

Intuitives Modell

Stellen Sie sich eine Druckpipeline vor: In der ersten Phase setzt jedes Unterpaket sein eigenes Manuskript (.tsQuellcode) in einseitige Korrekturabzüge (.d.ts); in der zweiten Phase werden Dutzende Korrekturabzüge in Verzeichnisreihenfolge zu einem Buch gebunden (release-taugliche.d.ts) und Kopf- und Fußzeilen vereinheitlicht (Export-Deklarationen).

Ohne diese Pipeline müsste Vue manuell eine Release-Typdatei pflegen; bei jeder Quellcode-Änderung müsste man synchron manuell nachziehen——ein Nährboden für Typ-Drift. Vues Ansatz ist:Typartefakte werden vollständig aus dem Quellcode generiert, niemals handgeschrieben。

Erste Phase: tsconfig.build.json legt den Ausgabebereich fest

tsconfig.build.jsonist die Konfiguration der ersten Phase dieser Pipeline. Sie erbt vom Root-tsconfig.jsonund überschreibt nur build-relevante Optionen.

📎 tsconfig.build.json:3-9

Schlüsseloptionen einzeln zerlegt:

• declaration: true: Lässt tsc für jede Quelldatei eine entsprechende.d.ts。
• emitDeclarationOnly: true：generieren, nur Typen, kein JS. JS wird von Rollup verantwortet; tsc ist hier reiner Typ-Extraktor.
• stripInternal: true: Alle Deklarationen, die mit@internalmarkiert sind, werden aus.d.tsentfernt. Dies ist Vues erste Schleuse zur Kontrolle der öffentlichen API-Oberfläche——interne Implementierungsdetails werden selbst dann nicht in die Release-Typen gelangen, wenn sieexportsind, solange sie mit@internalmarkiert sind.
• composite: false: Deaktiviert den inkrementellen Build-Modus von project references. Vue braucht hier keine paketübergreifende Inkrementalität; das Abschalten vermeidet zusätzlichen Zustand durch.tsbuildinfo.

includeDie

📎 tsconfig.build.json:10-23

-Liste legt präzise fest, welche Verzeichnisse an der Ausgabe teilnehmen:Beachten Sie, dass hiernur 12 Verzeichnisse aufgelistet sindpackages/。packages-private/、packages/dts-test/、packages/sfc-playground/, nicht das gesamteusw. sind nicht darunter. Das bedeutet: Die Typen privater Pakete und TestpaketeEintritt in die Release-Artefakte. Dies ist eine physische Isolation – nicht durch Konvention, sondern durch Konfiguration.

Nach Ausführung vontsc -p tsconfig.build.json --noChecklanden die Artefakte intemp/packages/<pkg>/src/*.d.ts. Beachten Sie--noCheck: Typprüfung wird übersprungen, nur emit wird ausgeführt. Die Typprüfung übernimmt ein separatestsc --noEmit, die Build-Phase wiederholt die Prüfung nicht, um Zeit zu sparen.

Zweite Phase: rollup.dts.config.js-Aggregation

Die zweite Phase wird vonrollup.dts.config.jsgesteuert. Ihr Einstieg führt zunächst eine Vorabvalidierung durch:

📎 rollup.dts.config.js:15-22

Fallstemp/packagesnicht existiert, bedeutet das, dass die erste Phase nicht ausgeführt wurde; das Skript beendet sich direkt mitprocess.exit(1)und weist darauf hin, zuersttscauszuführen. Dies ist derReihenfolgevertragder Pipeline: Die rollup-Phase ist stark abhängig von den Artefakten der tsc-Phase, beide sind unverzichtbar.

Anschließend werden alle Unterpaketverzeichnisse gelesen und dieTARGETSUmgebungsvariable für Subset-Builds unterstützt:

📎 rollup.dts.config.js:15-22

TARGETSDer Mechanismus erlaubt es, nur die Typen einiger weniger Pakete neu zu bauen, was den Feedback-Zyklus bei der Entwicklungs-Debugging erheblich verkürzt.

Der Kern isttargetPackages.map(...), das für jedes Paket eine Rollup-Konfiguration generiert:

📎 rollup.dts.config.js:23-42

Feldweise Erläuterung:

• input: ./temp/packages/${pkg}/src/index.d.ts: Der Einstieg ist die in der ersten Phase erzeugte Typdatei, nicht der Quellcode.ts。
• output.file: packages/${pkg}/dist/${pkg}.d.ts: Die Artefakte landen im jeweiligendist-Verzeichnis jedes Pakets, der Dateiname entspricht dem Paketnamen (z. B.vue.d.ts）。
• format: 'es': Typdateien einheitlich im ES-Module-Format.
• plugins: [dts(), patchTypes(pkg), ...(pkg === 'vue' ? [copyMts()] : [])]: Drei Plugins, die ersten beiden gelten für alle Pakete,copyMtsgilt nur für dasvue-Paket.

onwarnDer

📎 rollup.dts.config.js:23-42

-Hook verdient eine gesonderte Erwähnung:UNRESOLVED_IMPORTWährend des dts-Rollups werden alle nicht-relativen Imports standardmäßig externalisiert. Dies führt dazu, dass Rollup-Warnungen ausgibt. Aber das isterwartetes Verhaltenimport { X } from 'some-pkg'– diereturnin Typdateien sollten ohnehin als externe Referenzen erhalten bleiben und nicht mit eingebunden werden. Daher schluckt das Skript für „nicht aufgelöste Imports mit nicht-relativem Pfad" direktwarn。

beginnt. Wenn ein relativer Pfad-Import nicht aufgelöst wird, bedeutet das, dass die Artefakte der ersten Phase unvollständig sind – ein echtes Problem, das gemeldet werden muss. Diese Unterscheidung minimiert das Warnrauschen, ohne echte Fehler zu übersehen.

flowchart TD
    src["packages/*/src/*.ts<br/>源码类型"] --> tsc{"tsc -p tsconfig.build.json<br/>--noCheck"}
    tsc -->|"include 白名单命中"| temp["temp/packages/*/src/*.d.ts<br/>单包校样"]
    tsc -->|"不在 include 列表"| skip["不产出<br/>私有包/测试包被隔离"]
    temp --> check{"temp/packages 存在?"}
    check -->|"否"| exit["process.exit(1)<br/>提示先跑 tsc"]
    check -->|"是"| rollup["rollup-plugin-dts<br/>聚合为单文件"]
    rollup --> patch["patchTypes(pkg)<br/>内联导出 + 追加 types/"]
    patch --> vue{"pkg === 'vue'?"}
    vue -->|"是"| mts["copyMts()<br/>写 vue.d.mts"]
    vue -->|"否"| done["packages/pkg/dist/pkg.d.ts"]
    mts --> done

KopierentscDieses Diagramm verankert den Kontrollfluss der beiden Phasen:rollupDie Whitelist voncheckentscheidet, wer in die Pipeline gelangt,patchTypesDascopyMtsvonvueentscheidet, ob fortgefahren werden kann,

ist ein obligatorischer Schritt,

ist der

rollup-plugin-dts-paketspezifische Zweig..d.ts5.2 patchTypes: Die aggregierten Artefakte in eine release-taugliche Form umschreibenexport { A, B, C, ... }Intuitives ModelldefineComponentNachdem

patchTypesDutzende vonin eine Datei zusammengeführt hat, hat das Ergebnis die Form „zuerst eine Reihe von Typen deklarieren, am Ende mit einem riesigeneinheitlich exportieren". Das ist für Menschen schwer lesbar und löst bei manchen Toolchains (z. B. dem

-Aufruf von VitePress) den Fehler aus, dass „abgeleitete Typen nicht ohne Referenz benannt werden können".

patchTypesist dieserrenderChunkNachbearbeitungs-Formungsschritt

📎 rollup.dts.config.js:87-88

• isExported: „zentraler Export" wird in „Inline-Export vor Ort" umgewandelt, dann werden paketspezifische Typ-Erweiterungen angehängt.Datenstruktur: Zwei Sets und drei Durchläufegibt ein Rollup-Plugin zurück, die Kernlogik liegt imexport { ... }-Hook. Es verwaltet zwei Mengen:
• shouldRemoveExport: Zeichnet alleursprünglich exportiertenTypnamen auf (aus

-Deklarationen).

Step-by-Step Walkthrough

: Zeichnet alle

📎 rollup.dts.config.js:90-100

Typnamen auf, die aus dem großen Export-Block entfernt werden müssenExportNamedDeclaration(weil sie bereits inline exportiert wurden).Der Verarbeitungsablauf teilt sich in drei Durchläufe (pass 0 / pass 1 / pass 2), ein typisches „erst sammeln, dann umschreiben, zuletzt bereinigen"-Muster.Pass 0: Alle bereits exportierten Typnamen sammeln.export ... from '...'Über die AST-Top-Level-Knoten iterieren; für alleisExported。

, dieexportkein source haben

📎 rollup.dts.config.js:102-125

(also keineVariableDeclaration、TSTypeAliasDeclaration、TSInterfaceDeclaration、TSDeclareFunction、TSEnumDeclaration、ClassDeclaration-Re-Exports sind), wird der local name des Specifiers zuprocessDeclaration。

processDeclarationhinzugefügt.

📎 rollup.dts.config.js:70-85

Pass 1: Deklarationsknoten direkt mit

-Präfix versehen.idÜber Top-Level-Knoten iterieren, für

sechs Deklarationsarten wird_aufgerufen. Die Logik:Drei Schritte:1. Kein

→ direkt zurückgeben (z. B. anonyme Deklaration).shouldRemoveExport2. Name beginnt mitisExported→ überspringen. Dies ist dieprependLeftKonventionexport : Typen mit Unterstrich-Präfix sind interne Hilfstypen und werden nicht exportiert.

3. Den Namen zuVariableDeclarationhinzufügen; falls der Name in

📎 rollup.dts.config.js:104-115

ist (also ursprünglich exportiert wurde), an der Startposition der Deklarationdeclare consteinendeclare const a, b-String einfügen.processDeclarationBeachten Sie, dass derdeclarations[0]-Zweig eine zusätzliche Assertion hat:Wenn einemehrere declarators deklariert (z. B.

), wird direkt ein Fehler geworfen. Weil

📎 rollup.dts.config.js:127-171

nurExportNamedDeclarationverarbeitet, würde ein Multi-declarator zu einer übersehenen Verarbeitung führen. Hier wird

• schnelles ScheiternshouldRemoveExportstatt stiller Fehler gewählt – Ausdruck defensiver Programmierung.exported === localPass 2: Bereits inline exportierte Typen aus dem großen Export-Block entfernen.export { Foo as Bar }Über
• iterieren, für jeden Specifier:
• Falls sein local name inExportNamedDeclarationist und

(ausgenommen

📎 rollup.dts.config.js:172-183

code = s.toString()-Umbenennungsfälle), wird der Specifier entfernt.packages/${pkg}/typesBeim Entfernen wird MagicString präzise eingesetzt: Falls danach noch ein Specifier folgt, bis zum start des nächsten Specifiers löschen; falls es der letzte ist, bis zum end des vorherigen oder zum eigenen start löschen.

Warum muss inline exportiert werden?

Der Kommentar gibt den direkten Grund an:

📎 rollup.dts.config.js:45-51

Im Original heißt es: Alle Typen auf Inline-Export umstellen und aus dem großen Export-Block entfernen, sonst meldet der Aufruf in VitePressdefineComponentden Fehler „the inferred type cannot be named without a reference".

copyMts: Typen für Node ESM/CJS-Dualmodus bereitstellen

copyMtsDas Plugin wirkt nur auf dasvuePaket:

📎 rollup.dts.config.js:196-204

Es schreibt imwriteBundleHook den Inhalt vonvue.d.tsunverändert nachvue.d.mts。

Der Kommentar erklärt den Grund:

📎 rollup.dts.config.js:188-192

Gemäß derpackage.jsonexports-Spezifikation von TypeScript 4.7 müssen, um Typen für Node ESM und CJS gleichzeitig korrekt bereitzustellen,zwei unabhängige Deklarationsdateien existieren. Daher wird beim Buildvue.d.tseinmal alsvue.d.mts。

. Kopieren ist die günstigste Lösung und vermeidet einen erneuten Rollup-Durchlauf.

5.3 dts-built-test: Typ-Smoke-Test auf echten Artefakten

Intuitives ModellpatchTypesDie vorherigen beiden Abschnitte stellen sicher, dass Typ-Artefakte generiert werden können und die Form korrekt ist. Aber „generierbar" bedeutet nicht „korrekt generiert". Wennimportbei einem Durchlauf einen Bug hat und einen Export versehentlich löscht, kann das Artefakt immer noch generiert werden, aber der Nutzer stellt beim

dts-built-testfest, dass Typen fehlen.istein Typ-Smoke-Test, der auf echten Build-Artefakten läuftimport: Er testet nicht die Quelltypen, sondernvuedas veröffentlichte

Paket und verifiziert, dass wichtige Typformen nicht regressiert sind.

Datenstruktur: eine minimalisierte Typ-Assertion

📎 packages-private/dts-built-test/src/index.ts:3-6

Der Kern des gesamten Testpakets ist nur eine Datei:

• Zeilenweise Erläuterung:vueL1: AusdefineComponentwirdimportiert. Beachten Sie, dass hier derPaketnamepackages/vue/dist/vue.d.tsimportiert wird, kein relativer Pfad – es konsumiert das echte Artefakt
• ._CustomPropsNotErasedL3-6: Definiert eine Komponente
• mit leeren Props und leerem Setup.// #8376L8: Kommentar
• , verweist auf ein konkretes Issue.CustomPropsNotErasedL9-12: Exportiert_CustomPropsNotErased, Typ ist{ foo: string }der Schnitttyp von

unddefineComponent.{ foo: string }Dieser Test verifiziert:fooDer Rückgabetyp von。

〔Design-Inferenz und Architektur-Abwägung〕

📎 packages-private/dts-built-test/package.json:1-11

Hintergrundvermutung zu Issue #8376:

• private: trueDer Rückgabetyp von
• types: dist/index.d.tswird möglicherweise durch einen Conditional Type oder Mapped Type verarbeitet, wodurch zusätzliche Eigenschaften im Schnitttyp „gelöscht" werden. Dieser Test fixiert dieses Verhalten mit einer minimalen Reproduktion; bei einer Regression wird in der Typprüfungsphase ein Fehler gemeldet.
• dependenciesPaketkonfiguration: Workspace-Abhängigkeit zeigt auf echte Artefakteworkspace:*Schlüsselfelder:@vue/shared、@vue/reactivity、vue。

möglicherweise auf die Typen dieser beiden Pakete verweisen. Im Workspace-Modus verlinkt pnpm diese Abhängigkeiten symbolisch auf lokale Pakete, und die

dts-built-test-Felder der lokalen Pakete zeigen auf die Artefakte unter ihren jeweiligensrc/index.ts. So konsumiert die gesamte TestkettetscBuild-Artefaktetsc, nicht Quellcode.

〔Design-Inferenz und Architektur-Abwägung〕

Das Clevere an diesem Design ist: Es kodiert den „Typvertrag" alsdts-built-testkompilierbaren Codedts-test. Keine zusätzliche Assertion-Bibliothek nötig, keine Laufzeit,

• dts-built-testselbst ist der Test-Runner. Wenn die Typen stimmen, kompiliert es; wenn die Typen falsch sind, schlägt die Kompilierung fehl.Arbeitsteilung mit dts-testBeachten Sie, dass
• dts-testin diesem Kapitel undim nächsten Kapitel zwei verschiedene Dinge sind:(dieses Kapitel): konsumiert

Warum braucht es zwei Ebenen? Weil Quelltypen und Artefakttypen inkonsistent sein können.

sequenceDiagram
    participant CI as CI 脚本
    participant TSC as tsc (tsconfig.build.json)
    participant Rollup as rollup.dts.config.js
    participant Patch as patchTypes(pkg)
    participant Dist as packages/vue/dist
    participant BuiltTest as dts-built-test

    CI->>TSC: tsc -p tsconfig.build.json --noCheck
    TSC->>TSC: include 白名单过滤
    TSC-->>Rollup: temp/packages/*/src/*.d.ts
    Rollup->>Rollup: existsSync('temp/packages') 校验
    Rollup->>Rollup: rollup-plugin-dts 聚合
    Rollup->>Patch: renderChunk(code, chunk)
    Patch->>Patch: pass0 收集 isExported
    Patch->>Patch: pass1 prependLeft('export ')
    Patch->>Patch: pass2 移除大导出块 specifier
    Patch->>Patch: 追加 packages/vue/types/*
    Patch-->>Rollup: 改写后 code
    Rollup->>Dist: 写 vue.d.ts
    Rollup->>Dist: copyMts 写 vue.d.mts
    CI->>BuiltTest: tsc 类型检查
    BuiltTest->>Dist: import { defineComponent } from 'vue'
    Dist-->>BuiltTest: 类型形状
    BuiltTest-->>CI: 编译通过 / 报错

, das Entfernen vonpatchTypes, das Anhängen desdts-built-test-Verzeichnisses können alle unter der Voraussetzung korrekter Quelltypen Artefakt-Bugs einführen.

bewacht speziell diese letzte Meile.

Die vollständige Zeitsequenz der Typ-Pipeline

patchTypesKopierencode.replace(...)Dieses Sequenzdiagramm verankert die modulübergreifende Zusammenarbeit: CI treibt die beiden Phasen tsc und Rollup an,

1. die drei Durchläufe vonsind die Kernverarbeitung,start/endkonsumiert am Ende die Artefakte zur Verifikation.

2. Designüberlegungen, Fehlerbehebung und Produktions-FallstrickeMagicString kann Mappings erzeugen, sodass umgeschriebene Typdateien weiterhin auf den Quellcode zurückverfolgt werden können. Obwohl der Nutzen von Sourcemaps für Typdateien begrenzt ist, ist Konsistenz eine gute Praxis.

Schnelles Scheitern vs. stilles Fehlertolerieren

patchTypesAn mehreren Stellen verwendetassert：

📎 rollup.dts.config.js:74-74

📎 rollup.dts.config.js:107-108

📎 rollup.dts.config.js:147-148

Diese Assertions werfen sofort einen Fehler, wenn sie auf unerwartete AST-Formen stoßen. Im Vergleich dazuonwarndas stille Verschlucken vonUNRESOLVED_IMPORTinErwartetes Rauschen wird verschluckt, unerwartete Formen führen zu schnellem Scheitern. Das ist die richtige Haltung für Build-Skripte: Lieber den Build fehlschlagen lassen, als Typdateien mit falscher Form zu erzeugen.

Produktions-Fallstricke:_Präfix-Konvention

processDeclarationÜberspringen von Typen, die mit_beginnen:

📎 rollup.dts.config.js:76-78

Das bedeutet, dass jeder exportierte Typ im Quellcode, der mit_beginnt, nicht inline exportiert wird. Wenn ein Typ eigentlich öffentlich sein sollte, aber aufgrund eines Namens, der mit_beginnt, übersprungen wird, stößt der Nutzer auf den Fehler „Typ existiert nicht“.

Produktions-Fallstrick: Multi-Declarator-Assertion

📎 rollup.dts.config.js:106-115

Wenn in einem.d.tseindeclare const a, bauftritt, wirft der Build direkt einen Fehler. Dies ist bei handgeschriebenen Typen selten, aber wenn eine von einem Tool generierte Typdatei diese Form verwendet, wird es ausgelöst. Die Fehlermeldung gibt den problematischen Codeausschnitt aus, was die Lokalisierung erleichtert.

Zusammenfassung dieses Kapitels

Dieses Kapitel hat die vollständige Pipeline der Vue-Typartefakte nachverfolgt:

1. Erste Phase (tsc)：tsconfig.build.jsonverwendetincludeeine Whitelist, um den Ausgabebereich präzise abzugrenzen,emitDeclarationOnlygibt nur Typen aus,stripInternalentfernt interne Deklarationen. Die Artefakte landen intemp/packages/。

2. Zweite Phase (rollup)：rollup.dts.config.jsverwendetrollup-plugin-dts, um die Typen der einzelnen Pakete zu aggregieren,patchTypesschreibt durch drei AST-Durchläufe zentrale Exporte in Inline-Exporte um und hängt manuelle Erweiterungen aus demtypes/-Verzeichnis an.copyMtsFür dasvue-Paket werden zusätzlich.d.mts。

3. generiert. Validierungsphase (dts-built-test): Typ-Smoke-Tests auf den echten Build-Artefakten durchführen, um mit kompilierbarem Code die entscheidenden Typformen festzuschreiben und Typdrift zu verhindern.

Gedanken und Selbsttests zu diesem Kapitel

Minimalitätdts-built-testdes Testfalls entscheidend: Er muss den Auslösepfad des Bugs präzise reproduzieren. Jede zusätzliche Typumwandlung (wiedts-test, sieh, wie Vue mit Typvertragstests die öffentliche API-Oberfläche absichert.

Die drei bilden einen geschlossenen Kreislauf aus „Generieren → Formen → Validieren“, der sicherstellt, dass Quelltyp und veröffentlichter Typ strikt übereinstimmen. Dass das Typ-Paket selbst korrekt ist, bedeutet jedoch nicht, dass die Typform der öffentlichen API fixiert ist. Im nächsten Kapitel gehen wir tiefer inpackages-private/dts-test, um zu sehen, wie über 20.test-d.ts-Dateien mitexpectTypeund anderen Werkzeugen „Typen als API-Vertrag“ in regressionsfähige automatisierte Tests verwandeln.

Im vorherigen Kapitel haben wir die Generierungskette der Typdeklarationen verfolgt und gesehen, wie Vue durch Build-Konfiguration und Smoke-Tests sicherstellt, dass „Quelltyp“ und „veröffentlichter Typ“ strikt übereinstimmen. Doch der Typvertrag beschränkt sich nicht auf „ob die Form stimmt“, sondern entscheidender ist, „ob die API-Oberfläche den Erwartungen entspricht“ – welche Typen exportiert werden sollen, welche nicht, und ob generische Constraints präzise sind. Dieses Kapitel geht inpackages-private/dts-test, um zu sehen, wie Vue mit über 20.test-d.ts-Dateien „Typen als API-Vertrag“ in regressionsfähige automatisierte Tests umsetzt.

Das kognitive Modell von Typvertragstests: Die „Spezifikation“ in einen „ausführbaren Vertrag“ verwandeln

dts-testDie Dateien im-Verzeichnis haben ein kontraintuitives Merkmal: Sieerzeugen nahezu kein LaufzeitverhaltendefineComponent.test-d.tsx. Öffnet mandefineComponent({...}), sieht man zahlreichetsc/vue-tsc-Aufrufe, aber sie werden zur Testlaufzeit nie tatsächlich ausgeführt – diese Dateien werden nur vonnoEmit: truetypgeprüft,

📎 packages-private/dts-test/tsconfig.test.json:1-11

um sicherzustellen, dass kein JS erzeugt wird.noEmitDiese Konfiguration ist die „Laufzeitumgebung“ des gesamten Vertragssystems:jsx: preservedeaktiviert die Ausgabe von Artefakten,strictlässt TSX-Syntax für den TypeScript-Compiler zur Analyse bestehen,moduleResolution: bundleraktiviert alle strikten Prüfungen,libentspricht moderner Bundling-Semantik,esnextund führt gleichzeitigdom。ein..test-d.tsxOhne diese Konfiguration würde JSX in。

Alltagsanalogie: Normale Unit-Tests sind wie „die Maschine einschalten und sehen, ob sie raucht“, während Typvertragstests wie „vor Vertragsunterzeichnung Klausel für Klausel prüfen“ sind – es wird nicht tatsächlich gehandelt, sondern nur bestätigt, dass bei „vom Auftraggeber zu zahlender Betrag“ „Renminbi“ statt „US-Dollar“ steht. Wenn die Vertragsklauseln falsch sind, nützt es nichts, dass die Maschine noch so reibungslos läuft.

utils.d.tsstellt das gesamte Werkzeugset für diese „Vertragsprüfung“ bereit:

📎 packages-private/dts-test/utils.d.ts:7-21

Es gibt nur vier Schlüsselwerkzeuge:expectType<T>(value: T)behauptet, dassvaluegenau vom TypT；expectAssignable<T, T2 extends T>ist; behauptet, dassT2zuweisbar anT；IsUnion<T>ist; prüft, obTein Union-Typ ist;IsAny<T>prüft, obTvom Typanyist. Beachteimport 'vue/jsx'in L5 – es registriert den globalen JSX-Namensraum, sodass<MyComponent />in TSX vom Typsystem alsJSX.Element。

📎 packages-private/dts-test/utils.d.ts:7-21

IsUnionerkannt werden kann. Die Implementierung vonT extends any ? (U extends T ? false : true) : neververdient eine genauere Betrachtung:Tnutzt distributive bedingte Typen; wennextends falseein Union-Typ ist, wird jedes Mitglied unabhängig ausgewertet, und am Endefalseprüft, ob alle Zweigezurückgeben. Dies ist einExistenzbeweis auf Typebeneprops.jjj– er dient dazu, Verträge wie „

muss ein Union-Typ sein und darf nicht zu einer einzigen Signatur zusammengeführt werden“ zu fixieren.defineComponentSzenariogetriebener Walkthrough:

defineComponent.test-d.tsxDie vollständige Kette der Props-Typinferenz inhat 2260 Zeilen und ist der Kern des Vertragssystems. Wir versetzen uns in ein konkretes Szenario:defineComponent({ props: {...}, setup(props) {...} })Der Nutzer schreibtprops, und das Typsystem von Vue muss aus dersetupLaufzeitdeklaration den präzisen Typ desprops-Parameters inableiten. Diese Kette ist der komplexeste Teil des Vue-Typsystems.

Schritt 1: Den „erwarteten Typ“ als Vertragsgrundlage konstruieren

Die Testdatei definiert zuerst dasExpectedProps-Interface und schreibt den Typ, der für jede Props-Deklarationsart abgeleitet werden sollte,explizit fest：

📎 packages-private/dts-test/defineComponent.test-d.tsx:21-53

. Dieses Interface ist die schriftliche Version der „Vertragsklauseln“. Beachte einige subtile Typen:a?: number | undefined(optionale Props mitundefined）、aa: number(hat default, daher nicht optional),aaa: number | null（PropType<number | null>explizit deklariert),aaaa: number | undefined（required: true as constaber der Typ enthältundefined). Diese Unterschiede sind nicht willkürlich geschrieben; jede entspricht einem bestimmten Zweig in derprops-Deklaration.

Schritt 2: Mit verschiedenen DeklarationsartendefineComponent

📎 packages-private/dts-test/defineComponent.test-d.tsx:57-158

„füttern“propsDieses-Objekt ist dieerschöpfende Matrix der Deklarationsarten

• a: Numberund deckt alle Schreibweisen von Vue props ab:number | undefined
• aa: { type: Number as PropType<number | undefined>, default: 1 }– Konstruktor-Kurzform, abgeleitet alsnumber
• aaaa: { type: Number, required: true as const } —— as const– hat default, abgeleitet als nicht optionaltrueverhindert, dassbooleanzu
• b: { type: String, required: true as true } —— required: trueerweitert wird, und bewahrt den Literaltyp
• bb: { default: 'hello' }macht die Eigenschaft non-voidtype– kein
• cc: Array as PropType<string[]>, Typ wird nur über default abgeleitet
• l: [Date]– explizite TypkonvertierungDate | undefined
• ll: [Date, Number]– Array-Syntax, abgeleitet alsDate | number | undefined
• lll: [String, Number]– Multi-Typ-Array, abgeleitet als

er fixiert gleichzeitig „neue Schreibweise nutzbar“ und „alte Schreibweise ohne Regression“.setup / render / thisSchritt 3: An den drei Positionen

assertierenDies ist das raffinierteste Design des Vertragstests:。

📎 packages-private/dts-test/defineComponent.test-d.tsx:160-217

setup(props)Derselbe Props-Typ muss an drei verschiedenen Konsumpositionen korrekt abgeleitet werdenexpectType<ExpectedProps['x']>(props.x). In

📎 packages-private/dts-test/defineComponent.test-d.tsx:168-170

// @ts-expect-error should included 'undefined'In Kombination mitexpectType<number>(props.aaaa)——wird absichtlich eine fehlschlagende Assertion geschrieben, um mit@ts-expect-errorden Fehler zu schlucken. Dies verifiziert, dassprops.aaaaden Typnicht numberhat (andernfalls würde diese Zeile keinen Fehler werfen,@ts-expect-errorsondern stattdessen fehlschlagen, weil „kein Fehler zum Schlucken“ vorhanden ist). Dies ist die „Reverse-Assertion“-Technik des Typtests.

📎 packages-private/dts-test/defineComponent.test-d.tsx:204-205

// @ts-expect-error props should be readonlyIn Kombination mitprops.a = 1— verifiziert, dass props insetupschreibgeschützt sind. Wenn ein Refactoring versehentlich props veränderbar macht, wirft diese Zeile keinen Fehler mehr,@ts-expect-errorund

render()schlägt fehl.this.$propsInthis.xwird hingegen über die beiden Pfade

📎 packages-private/dts-test/defineComponent.test-d.tsx:221-279

undthisassertiert:this.a = 1L252-276 verifiziert, dass „deklarierte props auch aufthisexponiert werden müssen“, L278-279 verifiziert, dassthis.ceinen Fehler wirft (number（ref(1)props aufthis.d.e.valuesind ebenfalls schreibgeschützt). L281-287 verifiziert das Entpacken des setup-Rückgabewerts:stringist.value）、this.f.gwird entpackt),GT（reactiveist

(verschachtelte refs bleiben erhalten,

ist<MyComponent />branded Typen in

📎 packages-private/dts-test/defineComponent.test-d.tsx:296-322

werden nicht entpackt).<MyComponent>Vierter Schritt: Typvalidierung auf der TSX-Konsumentenseiteclass/style/key/ref/ref_forDer letzte Baustein des Typvertrags ist „wie der Nutzer diese Komponente verwendet“. Die props-Validierung vonin TSX ist ein unabhängiger Typpfad:：

📎 packages-private/dts-test/defineComponent.test-d.tsx:337-345

// @ts-expect-error missing required propsHier wird verifiziert, dasswrong prop typesalle deklarierten props akzeptiert, sowieggg="baz"diese eingebauten Attribute. Danach folgtgggReverse-Validierung'foo' | 'bar'）。

verifiziert, dass fehlende erforderliche props einen Fehler werfen;

flowchart LR
    A["props 声明对象<br/>L57-158"] --> B["defineComponent<br/>泛型推导"]
    B --> C["ExtractPropTypes<br/>运行时声明 → 类型"]
    C --> D["setup(props)<br/>L162-217"]
    C --> E["render() this.$props<br/>L221-279"]
    C --> F["TSX 消费端<br/>L296-345"]
    D --> G["expectType 断言<br/>契约锁定"]
    E --> G
    F --> G
    G --> H{"全部通过?"}
    H -->|是| I["类型契约成立"]
    H -->|否| J["tsc 报错<br/>CI 阻断合并"]

einen Fehler wirft (akzeptiert nurpropsDie gesamte Kette lässt sich mit einem Datenflussdiagramm zusammenfassen:KopierentscDer Schlüssel dieses Diagramms ist:

Dieselbe__typeProps、__typeEmitsDeklaration muss gleichzeitig die Typerwartungen von drei Konsumstellen erfüllen

defineComponent. Jede Abweichung in der Inferenz führt dazu, dasseinen Fehler wirft.Grenzen und Hintertüren:color='white'und bedingte TypverträgeappearanceDie Typinferenz von'outline'hat eine grundlegende Einschränkung:__typePropsLaufzeit-props-Deklarationen können „bedingte Typen“ nicht ausdrücken

__typeProps. Zum Beispiel die Einschränkung „wenn

📎 packages-private/dts-test/defineComponent.test-d.tsx:1803-1836

ConditionalProps, dann musscolorappearancesein“ lässt sich mit Laufzeit-Objektsyntax nicht schreiben. Vue bietet dafürcolor: 'white'und andere „Typ-Hintertüren“.appearance: 'outline': Notausstieg für bedingte props

• L1823-1824：<Comp color="white" />ist ein Union-Typ: entweder sindcolor: 'white'und
• L1825-1826：<Comp color="white" appearance="normal" />beide optional, oderappearanceund'outline'
• L1827：<Comp color="white" appearance="outline" />. Der Test verifiziert:

__typeEmitswirft einen Fehler —

__typeEmitsmusssein：

📎 packages-private/dts-test/defineComponent.test-d.tsx:1838-1885

besteht{ change: [id: number], update: [value: string] }〔Designinferenz und Architekturabwägung〕this.$props.onChange?.(123)Die Designmotivation vononChange?.('123')ist „das Typsystem Einschränkungen ausdrücken zu lassen, die zur Laufzeit nicht ausdrückbar sind“. Es nimmt nicht an der Laufzeit-props-Auflösung teil, sondern ist eine reine Typ-Ebene-Überlagerung. Der Preis ist, dass Nutzer die Konsistenz zwischen Typ und Laufzeitdeklaration manuell wahren müssen — deshalb heißt es „backdoor“ und nicht offizielle API.

📎 packages-private/dts-test/defineComponent.test-d.tsx:1887-1934

: Äquivalenz der beiden emits-Syntaxen{ (e: 'change', id: number): void; (e: 'update', value: string): void }unterstützt zwei Syntaxen, der Testsperrt beide gleichzeitigObjektsyntaxdrückt Parameter mit benannten Tupeln aus. Der Test verifiziert, dassbesteht,

__typeRefsDie Testkörper der beiden Syntaxen sind nahezu zeilenweise identisch__typeEl— das ist beabsichtigt: Der Vertrag verlangt, dass beide Schreibweisen

📎 packages-private/dts-test/defineComponent.test-d.tsx:1936-1952

__typeRefsvollständig äquivalentesParentTypverhalten erzeugen.__typeRefs: { child: ComponentInstance<typeof Child> }〔Designinferenz und Architekturabwägung〕refs.child.$refs.fooWarum zwei Syntaxen beibehalten? Die Objektsyntax ähnelt stärker der Schreibweise vonnumber。

📎 packages-private/dts-test/defineComponent.test-d.tsx:1963-1977

__typeEl, die Call-Signature-Syntax ähnelt stärker traditionellen TS-Ereignistypen. Vue muss beide unterstützen und konsistentes Verhalten garantieren. Die „zeilenweise gespiegelte“ Struktur des Tests ist der stärkste Äquivalenzbeweis.undElement: komponentenübergreifende Referenzen und Host-KnotentypenTypeElermöglicht der Elternkomponente, den Typ der Kindkomponenten-ref präzise zu kennen.ElementdeklariertCustomElement, sodass$elzu

eingeschränkt werden. Der Test verwendet das

function syntax w/ runtime propsInterface, um zu verifizieren, dassbeliebige Host-Typen akzeptieren kann.。

📎 packages-private/dts-test/defineComponent.test-d.tsx:1501-1545

〔Designinferenz und Architekturabwägung〕generics aren't supported with object runtime propsDies ist die Typ-Ebene-Garantie dafür, dass Vue 3 benutzerdefinierte Renderer unterstützt. Wäre<Comp3<string>>hart auf

Gegenseitige Ausschlussbedingungen von generischen Komponenten und Laufzeit-props

@ts-expect-errorDer Abschnitt

@ts-expect-errorsperrt eine wichtige Regel:Generische Komponenten können nicht mit Objekt-Laufzeit-props koexistieren@ts-expect-errorDer Kommentarin L1501 ist eine Vertragsdeklaration. L1525-1535 verifiziert, dass generisches setup + Objekt-props einen Fehler werfen; L1538-1539 verifiziert, dass

📎 packages-private/dts-test/defineComponent.test-d.tsx:1354-1362

einen Fehler wirft. Array-props hingegen erlauben Generics (L1464-1499).// @ts-expect-error missing prop〔Designinferenz und Architekturabwägung〕<Comp msg={123} />Die Ursache dieser Einschränkung ist die Reihenfolge der Typinferenz: Objekt-props benötigen, um zuerst den Typ zu bestimmen, während Generics erst bei der Instanziierung bestimmt werden können — beide kollidieren. Array-props nehmen nicht an der Typextraktion teil, daher kollidieren sie nicht. Der Vertragstest fixiert diese „Typsystem-Einschränkung“ als regressionsfähige Assertion.Designüberlegungen, Fehlererholung und Produktions-FallstrickeexpectType<JSX.Element>(...)Das zweischneidige Schwert von@ts-expect-errorist das Kernwerkzeug des Typvertragstests, hat aber eine tödliche Falle:expectTypeWenn der Code darunter keinen Fehler mehr wirft,

IsAnyundIsUnion: Existenzbeweis auf Typebene

📎 packages-private/dts-test/defineComponent.test-d.tsx:1991-1993

expectType<IsAny<typeof props.foo>>(false)validiertprops.foonichtany. Dies istumgekehrter Vertrag: Es wird nicht nur gefordert, dass der Typ korrekt ist, sondern auch, dass der Typ nicht zuany」。anydegenerieren darf. ist ein schwarzes Loch des Typsystems; jedesanylässt nachfolgende Assertions bedeutungslos werden.

📎 packages-private/dts-test/defineComponent.test-d.tsx:195-196

expectType<IsUnion<typeof props.jjj>>(true)validiertjjjist ein Union-Typ.jjjdeklariert als((arg1: string) => string) | ((arg1: string, arg2: string) => string), wenn das Typsystem es zu einer einzigen Signatur zusammenführt,IsUniongibtfalsezurück, Test schlägt fehl.

Impliziter Vertrag der Deklarationsreihenfolge

📎 packages-private/dts-test/defineComponent.test-d.tsx:1784-1801

Dieser Kommentar ist äußerst wichtig:code generated by tsc / vue-tsc, make sure this continues to work so we don't accidentally change the args order of DefineComponent。DefineComponenthat 13 generische Parameter, die Reihenfolge istÖffentlicher Vertrag——vue-tscDer generierte Komponententyp hängt von dieser Reihenfolge ab. Der Test verwendetdeclare const MyButton: DefineComponent<...>und schreibt alle 13 Parameter explizit aus, um die Reihenfolge zu fixieren.

Dateiübergreifender Vertrag:componentInstance.test-d.tsxErgänzung zu

componentInstance.test-d.tsxhat nur 154 Zeilen, deckt aber alle Eingabeformen desComponentInstanceUtility-Typs ab:

📎 packages-private/dts-test/componentInstance.test-d.tsx:10-40

ComponentInstance<typeof CompSetup>Extrahiert den Instanztyp aus demdefineComponentErgebnis;ComponentInstance<typeof CompFunctional>Extrahiert aus funktionalen Komponenten;ComponentInstance<typeof CompFunction>Extrahiert aus nackten Funktionen. Alle drei müssen dieComponentPublicInstanceBasisklasse ableiten.

📎 packages-private/dts-test/componentInstance.test-d.tsx:71-116

Noch extremer ist das „nackte Objekt ohnedefineComponentWrapper“:CompObjectSetup、CompObjectData、CompObjectNoPropsAlle drei Formen müssen vonComponentInstancekorrekt extrahiert werden können. Besonders L113-114 ist kontraintuitiv:CompObjectNoPropshat keineprops-Deklaration, abercompObjectNoProps.testwird dennoch alsstring | undefinedabgeleitet – dies ist der von derComponentPublicInstanceBasisklasse bereitgestellte Fallback.

📎 packages-private/dts-test/componentInstance.test-d.tsx:143-147

Der#12751-Test in L141 fixiert eine Grenze:__typeEmitsdeklarierte'update:visible'-Ereignis sollte auf der Instanz alscomp['onUpdate:visible'](String-Schlüssel mit Doppelpunkt) exponiert werden, und$propshat den Typ{ 'onUpdate:visible'?: (value?: boolean) => any }. L152-153 validiertcomp['$props']['$props']Fehler – verhindert rekursive Selbstreferenz des Typs.

Zusammenfassung dieses Kapitels

dts-testDas Verzeichnis verwendet über 20.test-d.ts-Dateien, um „Typ als API-Vertrag“ in regressionsfähige automatisierte Tests umzusetzen. Der Kernmechanismus hat drei Ebenen:

1. Werkzeug-Ebene：expectType、expectAssignable、IsUnion、IsAnyBietet Typ-Assertion-Primitive,@ts-expect-errorBietet umgekehrte Assertion-Fähigkeit.

2. Vertrags-Ebene：ExpectedPropsDie Schnittstelle schreibt explizit fest, „welcher Typ abgeleitet werden soll“,propsDie Deklarationsmatrix zählt alle Schreibweisen erschöpfend auf, drei Konsumstellen (setup/render/TSX) werden kreuzvalidiert.

3. Hintertür-Ebene：__typeProps、__typeEmits、__typeRefs、__typeElBietet eine Escape-Luke für Typbeschränkungen, die zur Laufzeit nicht ausgedrückt werden können, und fixiert gleichzeitig die Äquivalenz der beiden emits-Syntaxen.

Denkanstöße und Selbsttests dieses Kapitels

// @ts-expect-error
;<Comp color="white" appearance="normal" />

sind Bestandteile der „Typ-ABI".

Typvertragstests lösen „ob die API-Oberfläche den Erwartungen entspricht". Aber Typen sind nur die Hälfte der Vue-Engineering – die andere Hälfte ist „wie Benutzer das Verhalten dieser APIs in Echtzeit im Browser verifizieren können". Das nächste Kapitel führt in den SFC Playground ein und zeigt, wie Vue Compiler, Runtime und Typsystem in eine browserinterne Echtzeit-Debugging-Umgebung verpackt, sodass Benutzer im Moment der Codeänderung die Kompilierungsartefakte und Laufzeitergebnisse sehen.IsAny/IsUnion), „ob die Reihenfolge generischer Parameter stabil ist" (DefineComponent13 Parameter), „Renderer-Unabhängigkeit" (__typeElnicht aufElementbeschränkt). Sobald diese Einschränkungen durchbrochen werden, driften die IDE-Hinweise auf Benutzerseite,vue-tscdie generierten Typen. Und die Stabilität von Typverträgen muss letztlich der täglichen Debugging-Erfahrung von Entwicklern dienen – im nächsten Kapitel betreten wirpackages-private/sfc-playgroundund sehen, wie ein reiner Frontend-Playground den geschlossenen Kreislauf von SFC-Kompilierung und Echtzeit-Vorschau im Browser vollendet.

Im vorherigen Kapitel haben wir mit über 20.test-d.tsDateien „Typen als API-Vertrag" in der CI festgenagelt. Aber Typverträge beantworten nur „wie die API-Oberfläche aussieht", sie können nicht beantworten „wie diese SFC tatsächlich kompiliert aussieht" oder „ob die Renderergebnisse im SSR-Modus konsistent sind". Um die letzten beiden Fragen zu beantworten, brauchte das Vue-Team eine Sandbox, die die vollständige Kompilierungspipeline im Browser ausführen kann – das istpackages-private/sfc-playground. Es unterscheidet sich grundlegend von den öffentlichen Paketen unterpackages/:package.jsonin"private": trueund"version": "0.0.0" 📎 packages-private/sfc-playground/package.json:2-4, was bedeutet, dass es niemals auf npm veröffentlicht wird, sondern nur ein offizielles Debugging-Tool ist. In seinen Abhängigkeiten zeigtvueaufworkspace:* 📎 packages-private/sfc-playground/package.json:19, also auf lokale Quellcode-Build-Artefakte statt auf die stabile Version auf npm – was den Playground natürlicherweise zu einer „lebenden Demonstration des aktuellen Commits" macht. Dieses Kapitel konzentriert sich auf drei Fragen: Wie initialisiert der Einstiegspunkt, wie steuert der Header Zustandswechsel, und wie werden Build-Zeit-Konstanten injiziert.

I. Minimalismus des Einstiegspunkts: main.ts und der Initialisierungsvertrag des ReplStore

Intuitives Modell

main.tshat nur 9 Zeilen, wie ein „Selbsttest-Skript beim Start": Bevor die Vue-Anwendung gemountet wird, wird zuerst inwindoweine globale Konfiguration eingefügt, die Vue DevTools mitteilt, „welche App standardmäßig ausgewählt ist". Ohne diesen Schritt würde DevTools beim Öffnen mit mehreren App-Instanzen konfrontiert (der Playground selbst + der im Benutzer-REPL ausgeführte Code) und könnte nicht automatisch fokussieren, was die Debugging-Erfahrung auf manuelles Umschalten degradieren würde.

Datenstruktur und globale Seiteneffekte

main.tsDer Kern voncreateAppist nichtwindowsondern das verschmutzende Schreiben in

📎 packages-private/sfc-playground/src/main.ts:4-7

// @ts-expect-error Custom window property
window.VUE_DEVTOOLS_CONFIG = {
  defaultSelectedAppId: 'repl',
}

Hier gibt es zwei bemerkenswerte Engineering-Details:

Step-by-Step: Von HTML zum Mounten

Der Ausführungsfluss ist extrem kurz, aber jeder Schritt hat implizite Einschränkungen:

1. Der Browser lädtindex.html, das<div id="app">enthält (in diesem Material nicht bereitgestellt, abermount('#app')lässt sich rückerschließen).

2. Modulgraph-Auflösung:main.tsDasimport App from './App.vue' 📎 packages-private/sfc-playground/src/main.ts:2am Anfang von@vitejs/plugin-vuelöst die SFC-Kompilierung von

4. mount('#app')registriert, und ein Schreiben der Konfiguration nach dem Mount kann die erste Auswahl nicht mehr beeinflussen.App.vuelöst das Setup vonReplStoreaus und erstellt dannApp.vue(in

flowchart TD
    load["浏览器加载 index.html"] --> parse["解析 main.ts 模块图"]
    parse --> sfc["@vitejs/plugin-vue 编译 App.vue"]
    sfc --> setcfg["写入 window.VUE_DEVTOOLS_CONFIG"]
    setcfg --> check{"VUE_DEVTOOLS_CONFIG 已设置?"}
    check -->|是| mount["createApp(App).mount('#app')"]
    check -->|否| devtools["DevTools 无法默认选中 repl"]
    mount --> appsetup["App.vue setup 创建 ReplStore"]
    appsetup --> ready["Playground 就绪"]
    devtools --> mount

Kopieren

main.tsDesign-Überlegungen und FallstrickeDer Minimalismus vonApp.vueist absichtlich:ReplStoreDer Einstiegspunkt übernimmt nur zwei Aufgaben: „globale Seiteneffekt-Injektion + Mounting". Jegliche Geschäftslogik sollte hier nicht auftauchen. Dies ist die Abwägung des Playgrounds als „Debugging-Tool" statt als „Produkt" – es benötigt keine SSR-Kompatibilität, keine mehrfachen Einstiegspunkte, kein Lazy Loading.

---

Zwei, Header.vue: computed abgeleiteter Zustand und emit unidirektionaler Datenfluss

Intuitives Modell

Header.vueist das „Kontrollpanel" des Playgrounds – Versionsauswahl, PROD/DEV-Umschaltung, SSR-Schalter, Theme-Umschaltung, Teilen, Herunterladen. Es selbsthält keinen Geschäftszustand, alle Zustände stammen ausprops.storeund booleschen Props, alle Änderungen werden überemitan die Elternkomponente gemeldet. Ohne diese Einschränkung „dumme Komponente + Event-Bubbling" würde der Header zu einem Hotspot verstreuter Zustände werden, und die Seiteneffekte von Versionswechsel und SSR-Umschaltung könnten nicht zentral verwaltet werden.

Datenstruktur- und Feldanalyse

Die Props-Definition des Headers ist der Schlüssel zum Verständnis seiner Verantwortlichkeiten:

📎 packages-private/sfc-playground/src/Header.vue:13-19

const props = defineProps<{
  store: ReplStore
  prod: boolean
  ssr: boolean
  autoSave: boolean
  theme: 'dark' | 'light'
}>()

Die fünf Props teilen sich in zwei Kategorien auf:

• store: ReplStore: die einzige Zustandscontainer-Referenz, stammt aus@vue/repl. Der Header liest darüberstore.loading、store.vueVersion、store.typescriptVersion, und schreibt direkt instore.vueVersion。
• vier boolesche/Literal-Props：prod、ssr、autoSave、theme. Sie sindkontrollierter Zustand, der Header liest nur und schreibt nicht, Änderungen müssenemit。

die entsprechende emit-Liste📎 packages-private/sfc-playground/src/Header.vue:20-28：

const emit = defineEmits([
  'toggle-theme',
  'toggle-ssr',
  'toggle-prod',
  'toggle-autosave',
  'reload-page',
])

Beachten Sietoggle-themeobwohl vontoggleDark()internemit, abertoggle-ssr/toggle-prod/toggle-autosaveist im Template direkt$emitdas📎 packages-private/sfc-playground/src/Header.vue:102-118. Diese Mischung ist ein häufiger Vue 3<script setup>-Stil:Bei Bedarf an Seiteneffekten Funktion emit verwenden, bei reiner Weiterleitung Template$emit。

Step-by-Step: Versionsanzeige und -wechsel

Szenario: Benutzer öffnet den Playground, der Header muss die aktuelle Vue-Version anzeigen.

Schritt 1: computed abgeleiteter Anzeigetext

📎 packages-private/sfc-playground/src/Header.vue:30-37

const vueVersion = computed(() => {
  if (store.loading) {
    return 'loading...'
  }
  return store.vueVersion || `@${__COMMIT__}`
})

Hier gibt es drei Prioritätsebenen:loading-Zustand →'loading...'; Benutzer hat explizit Version gewählt →store.vueVersion; andernfalls →@${__COMMIT__}(aktueller Commit-Kurzhash).__COMMIT__ist eine zur Build-Zeit injizierte Konstante, wird im nächsten Abschnitt detailliert beschrieben.

Schritt 2: VersionSelect Zwei-Wege-Bindung

📎 packages-private/sfc-playground/src/Header.vue:88-88

<VersionSelect
  :model-value="vueVersion"
  @update:model-value="setVueVersion"
  pkg="vue"
  label="Vue Version"
>

Beachten Sie hierwurde nichtv-modelverwendet, sondern explizit aufgeteilt in:model-value + @update:model-value. Der Grund ist, dassvueVersionein computed ist (schreibgeschützt), nicht direkt zwei-Wege-gebunden werden kann; muss übersetVueVersiondiese Setter-Funktion geschrieben werdenstore.vueVersion：

📎 packages-private/sfc-playground/src/Header.vue:39-41

async function setVueVersion(v: string) {
  store.vueVersion = v
}

function resetVueVersion() {
  store.vueVersion = null
}

Schritt 3: TypeScript-Version im Vergleich

📎 packages-private/sfc-playground/src/Header.vue:76-80

<VersionSelect
  v-model="store.typescriptVersion"
  pkg="typescript"
  label="TypeScript Version"
/>

Die TypeScript-Version verwendetv-model, weilstore.typescriptVersioneine beschreibbare normale Eigenschaft ist, kein computed-Wrapping benötigt.Dieselbe Komponente verwendet zwei Bindungsarten im selben Template, was genau die intuitive Verkörperung von „kontrolliert vs. unkontrolliert" ist.

Theme-Umschaltung: Kombination von Seiteneffekt und emit

📎 packages-private/sfc-playground/src/Header.vue:58-66

function toggleDark() {
  const cls = document.documentElement.classList
  cls.toggle('dark')
  localStorage.setItem(
    'vue-sfc-playground-prefer-dark',
    String(cls.contains('dark')),
  )
  emit('toggle-theme', cls.contains('dark'))
}

Diese Funktion macht drei Dinge: DOM-Klasse manipulieren, in localStorage persistieren, emit zur Benachrichtigung der Elternkomponente.Beachten Sie, dass sie nicht direktprops.themeändert – weil Props schreibgeschützt sind, die Elternkomponente erst nach Erhalt vontoggle-themeaktualisierttheme, was wiederum den:title-Text im Template steuert📎 packages-private/sfc-playground/src/Header.vue:123。

Versteckte Logik: metaKey-Zweig von copyLink

📎 packages-private/sfc-playground/src/Header.vue:47-56

async function copyLink(e: MouseEvent) {
  if (e.metaKey) {
    resetVueVersion()
    // hidden logic for going to local debug from play.vuejs.org
    window.location.href = 'http://localhost:5173/' + window.location.hash
    return
  }
  await navigator.clipboard.writeText(location.href)
  alert('Sharable URL has been copied to clipboard.')
}

Dies ist eineEntwickler-Hintertür: Aufplay.vuejs.orgCmd gedrückt halten und auf den Teilen-Button klicken, springt zulocalhost:5173(lokaler Dev-Server) und nimmt den aktuellen URL-Hash mit. Der Hash kodiert den vollständigen REPL-Zustand (Quellcode, Version, Optionen), sodass lokales Debugging Online-Probleme reproduzieren kann. Der Kommentar// hidden logic for going to local debug from play.vuejs.org 📎 packages-private/sfc-playground/src/Header.vue:47-56kennzeichnet explizit, dass dies eine absichtlich versteckte Funktion ist.

flowchart TD
    click["用户点击 Share 按钮"] --> meta{"e.metaKey 按下?"}
    meta -->|是| reset["resetVueVersion() 置 null"]
    reset --> jump["跳转 localhost:5173 + hash"]
    jump --> local["本地 dev server 复现"]
    meta -->|否| copy["navigator.clipboard.writeText(location.href)"]
    copy --> check{"写入成功?"}
    check -->|是| alert["alert 提示已复制"]
    check -->|否| fail["静默失败 (无 catch)"]

Design-Überlegungen und Fallstricke

Fallstrick 3:currentCommitundvueVersionVergleich. Im Template:class="{ active: vueVersion === \@${currentCommit}\ }" 📎 packages-private/sfc-playground/src/Header.vue:88-88Durch String-Verkettung vergleichen. Wenn__COMMIT__die Injektion fehlschlägt (wird zuundefined), wird hier daraus'@undefined', was niemals übereinstimmt. Die Zuverlässigkeit der Build-Zeit-Konstanten-Injektion bestimmt direkt die UI-Korrektheit – genau das ist das Thema des nächsten Abschnitts.

---

Drei, Build-Zeit-Konstanten-Injektion: Die doppelte Verantwortung von __COMMIT__ und copyVuePlugin

Intuitives Modell

vite.config.tsist die „Montagehalle“ des Playgrounds: Es führt zur Build-Zeitgit rev-parseaus, um den Commit-Hash zu erhalten, und macht ihn überdefinezu einer globalen Konstante__COMMIT__; gleichzeitig kopiert es über ein benutzerdefiniertes Plugin die ESM-Browser-Artefakte unterpackages/vue/dist/in das Ausgabeverzeichnis des Playgrounds. Ohne diesen Schritt könnte der Playground die „Vue-Laufzeit des aktuellen Commits“ nicht im Browser laden – er wäre auf die stabile Version von npm angewiesen und würde die Bedeutung einer „Live-Demo“ verlieren.

Datenstruktur und Build-Zeit-Konstanten

📎 packages-private/sfc-playground/vite.config.ts:7-9

const commit = spawnSync('git', ['rev-parse', '--short=7', 'HEAD'])
  .stdout.toString()
  .trim()

spawnSyncführt den git-Befehl synchron aus,--short=7nimmt den 7-stelligen Kurz-Hash. Die synchrone Ausführung ist absichtlich so gewählt:Die Konfigurationsdatei benötigt den Wert voncommitbereits während des Modulladens, asynchron würde die Reihenfolge der Vite-Konfigurationsauflösung durcheinanderbringen.

📎 packages-private/sfc-playground/vite.config.ts:23-26

define: {
  __COMMIT__: JSON.stringify(commit),
  __VUE_PROD_DEVTOOLS__: JSON.stringify(true),
},

defineist VitesTextersetzungsmechanismus: Alle__COMMIT__im Quellcode werden durch das Ergebnis vonJSON.stringify(commit)ersetzt (also durch ein Zeichenkettenliteral mit Anführungszeichen).JSON.stringifyist erforderlich – wenn man direktcommitschreiben würde, würde es nach der Ersetzung zu einem nackten Bezeichnerabc1234werden und als Variablenname statt als Zeichenkette behandelt.

Step-by-Step: Das Artefakt-Verschieben von copyVuePlugin

📎 packages-private/sfc-playground/vite.config.ts:32-63

function copyVuePlugin(): Plugin {
  return {
    name: 'copy-vue',
    generateBundle() {
      const copyFile = (file: string) => {
        const filePath = path.resolve(
          import.meta.dirname,
          '../../packages',
          file,
        )
        const basename = path.basename(file)
        if (!fs.existsSync(filePath)) {
          throw new Error(
            `${basename} not built. ` +
              `Run "nr build vue -f esm-browser" first.`,
          )
        }
        this.emitFile({
          type: 'asset',
          fileName: basename,
          source: fs.readFileSync(filePath, 'utf-8'),
        })
      }

      copyFile(`vue/dist/vue.esm-browser.js`)
      copyFile(`vue/dist/vue.esm-browser.prod.js`)
      copyFile(`vue/dist/vue.runtime.esm-browser.js`)
      copyFile(`vue/dist/vue.runtime.esm-browser.prod.js`)
      copyFile(`server-renderer/dist/server-renderer.esm-browser.js`)
    },
  }
}

Die Kernpunkte einzeln analysiert:

1. generateBundleHook: Wird ausgeführt, nachdem Rollup das Bundle erzeugt hat, aber bevor es auf die Festplatte geschrieben wird. Zu diesem Zeitpunkt kann manemitFilezusätzliche Dateien in die Artefakte einfügen.

2. import.meta.dirname: Die von Node 20.11+ bereitgestellte ESM-Version von__dirname. Der Pfad../../packagesgeht vonpackages-private/sfc-playground/zum Repository-Stamm hinauf und dann inpackages/。

3. Existenzprüfung + explizite Fehlermeldung: Wennvue.esm-browser.jsnicht existiert, wird ein Fehler mit Reparaturanweisung geworfenRun "nr build vue -f esm-browser" first.. Dies istein Musterbeispiel für Developer Experience– die Fehlermeldung sagt einem direkt, wie man es repariert.

4. Fünf Artefakte：vuein Vollversion/Runtime-Version × dev/prod, plusserver-renderer. Diese fünf Dateien sind genau die Kandidatenmenge, die der Playground im Browser dynamisch importiert, entsprechend dem Versionswechsel und dem SSR-Schalter im Header.

Der vollständige Datenfluss des Versionswechsels

Betrachtet man densetVueVersionim Header zusammen mit den Artefakten von copyVuePlugin:

flowchart LR
    user["用户选择版本"] --> setver["setVueVersion(v)"]
    setver --> store["store.vueVersion = v"]
    store --> repl["@vue/repl 内部"]
    repl --> fetch{"版本来源?"}
    fetch -->|"@commit"| local["加载本地 vue.esm-browser.js"]
    fetch -->|"3.4.0"| cdn["从 CDN 加载"]
    local --> compile["浏览器内编译 SFC"]
    cdn --> compile
    compile --> preview["实时预览"]

Beachtet den speziellen Wert@${__COMMIT__}: Er entspricht den lokalen Artefakten, die copyVuePlugin kopiert hat, nicht dem CDN. Deshalb muss der Playground die Browser-Build-Artefakte von Vue hineinkopieren –die Option „This Commit“ benötigt lokale Dateien。

Design-Überlegungen und Stolperfallen

---

Design-Überlegung: Die Architektur-Abwägungen des Playgrounds

Betrachtet man die drei Unterabschnitte zusammen, folgt die Architektur des Playgrounds einem klaren Prinzip:Trennung von „Zustand“ und „Nebenwirkungen“, Trennung von „Build-Zeit“ und „Laufzeit“。

• main.tsführt nur globale Nebenwirkungs-Injektion durch und berührt keinen Business-Zustand.
• Header.vueist eine reine Präsentationskomponente, der Zustand fließt über Props hinein und über emit hinaus.
• vite.config.tsverfestigt die Build-Zeit-Information „aktueller Commit“ zu einer Konstante, die zur Laufzeit nur gelesen wird.

Der Preis istZustandsverteilung：storeIn@vue/replist der boolesche Zustand in der Elternkomponente, die DOM-Klasse aufdocument.documentElement, und in localStorage liegt noch eine weitere Kopie. Vier Zustandsorte müssen manuell synchronisiert werden; jede Nichtsynchronisation führt zu UI-Inkonsistenz.

---

Kapitelzusammenfassung

Dieses Kapitel analysiertpackages-private/sfc-playgrounddie drei Kerndateien:

1. main.ts: 9-zeiliger Einstiegspunkt, der Kern istwindow.VUE_DEVTOOLS_CONFIGdie Injektionsreihenfolge – muss vormounterfolgen.

2. Header.vue: durchcomputedableitenvueVersion, durchemitalle Zustandsänderungen melden.copyLinkdiemetaKeyDer Zweig ist eine versteckte lokale Debug-Hintertür.

3. vite.config.ts：spawnSyncCommit-Hash holen,defineinjizieren__COMMIT__，copyVuePlugindie fünf Vue-Browser-Artefakte in das Playground-Artefaktverzeichnis kopieren.

Der rote Faden durch alle drei istdie Grenze zwischen Build-Zeit-Konstanten und Laufzeit-Zustand：__COMMIT__ist eine schreibgeschützte Build-Zeit-Tatsache,store.vueVersionist eine veränderbare Laufzeit-Auswahl, dasvueVersioncomputed im Header vereinheitlicht beides zu einem Anzeige-String.

Kapitelreflexion und Selbsttest

---

ausgeführt werden muss". In einer CI-Umgebung könnte der Entwickler fälschlicherweise auf einen Pfadkonfigurationsfehler, Berechtigungsproblem oder nicht initialisiertes Git-Submodul schließen und viel Zeit mit der Fehlersuche verschwenden. Daspackages-private/template-explorerim Originalcode bindet „Symptom" und „Reparaturaktion" aneinander, ein entscheidendes Detail im Developer-Experience-Design. Dies erklärt auch, warum das Build-Skript von Playground eine klare Abhängigkeitsreihenfolge zum Vue-Kern-Build-Skript haben muss.

Das nächste Kapitel geht in@vue/compiler-domund zeigt, wie Vue die Zwischenprodukte des Compilers (AST, Transformationsergebnisse, Codegenerierung) visualisiert, sodass Entwickler jeden Schritt der Transformation vom Template zur Renderfunktion schrittweise beobachten können. Anders als die „End-to-End-Blackbox" von Playground ist Template Explorer eine „Whitebox-Sonde".@vue/compiler-ssrDamit haben wir gesehen, wie SFC Playground die Kompilierungspipeline in den Browser bringt: Einstiegsinitialisierung, Header-Zustandswechsel und Build-Zeit-Konstanten-Injektion bilden gemeinsam eine in Echtzeit debugbare Sandbox. Doch die Perspektive von Playground ist stets „Kompilierung und Ausführung eines ganzen SFC", sie beantwortet nicht direkt „was der Compiler mit einem bestimmten Template-Ausdruck tatsächlich macht". Das nächste Kapitel betritt Template Explorer und zeigt, wie er

Im vorherigen Kapitel haben wir gesehen, wie der SFC Playground die gesamte Kette von „SFC-Eingabe → Kompilierung im Browser → Echtzeit-Vorschau“ als Blackbox kapselt: Entwickler sehen das endgültige Rendering-Ergebnis, aber nicht, was der Compiler dazwischen tut. Wenn im Template eine benutzerdefinierte Direktive steht oder nach dem Aktivieren von hoistStatic plötzlich eine Reihe von _hoisted_1-Variablen im Output auftaucht, kann der Playground nicht beantworten, „warum der Compiler das so generiert“. Der Template Explorer ist genau gegensätzlich positioniert: Er legt die Kompilierungsartefakte von @vue/compiler-dom und @vue/compiler-ssr, den AST, Fehlermarkierungen sowie die Positionszuordnung von Quellcode zu Artefakt vollständig offen. Sein Kern ist nicht „Ausführen“, sondern „Beobachten“. Dieses Kapitel dreht sich um drei Dateien: index.ts übernimmt den Compiler-Aufruf und die bidirektionale SourceMap-Zuordnung, options.ts verwaltet mit reactive Dutzende von CompilerOptions und treibt die UI an, theme.ts passt das Monaco-Editor-Theme an.

一、Compiler-Aufruf und bidirektionale SourceMap-Zuordnung: index.ts

Intuitives Modell

Der Template Explorer istindex.tswie eine „bidirektionale Übersetzungsmaschine“: Links wird das Template eingegeben, rechts wird die Render-Funktion ausgegeben. Aber sie kann mehr als eine Übersetzungsmaschine – wenn du den Cursor auf eine Zeile links setzt, wird rechts das entsprechende Artefakt hervorgehoben; umgekehrt wird, wenn du den Cursor rechts platzierst, links das entsprechende Template hervorgehoben. Ohne SourceMap-Zuordnung würde dieses Tool zu zwei nebeneinanderliegenden Textfeldern degenerieren, und Entwickler könnten nur mit bloßem Auge vergleichen und keine Kausalkette von „Template-Zeile X → Artefakt-Zeile Y“ herstellen.

Datenstruktur und Speicherlayout

index.tsEnthält keine komplexen Structs, aber einige entscheidende Zustandsvariablen auf Modulebene, die das Verhalten des gesamten Tools bestimmen:

lastSuccessfulCodeundlastSuccessfulMapsind der Cache des Kompilierungsergebnisses📎 packages-private/template-explorer/src/index.ts:74-75. Ersteres ist ein String, letzteres istSourceMapConsumer | undefined. Beachte:lastSuccessfulMapist initialundefined, und wird nur zugewiesen, wenn die Kompilierung erfolgreich war undmapexistiert📎 packages-private/template-explorer/src/index.ts:99-100. Dieserundefined-Zustand ist die Guard-Bedingung für die gesamte spätere Cursor-Zuordnungslogik – wenn die Kompilierung fehlschlägt, wird die Zuordnungsfunktion automatisch still deaktiviert, statt eine Exception zu werfen.

PersistedStateDas Interface definiert die Form des in localStorage und URL-Hash persistierten Zustands📎 packages-private/template-explorer/src/index.ts:26-30：src(Template-Quellcode),ssr(ob SSR-Modus),options(Compiler-Optionen). Hier gibt es ein entscheidendes Design:optionshat den Typ des vollständigenCompilerOptions, aber bei der tatsächlichen Persistierung werden nur „von den Standardwerten abweichende Einträge“ gespeichert; diese Trim-Logik wird inreCompileerledigt.

sharedEditorOptionsSind die von beiden Editoren gemeinsam genutzten Konstruktionsoptionen📎 packages-private/template-explorer/src/index.ts:26-30：fontSize: 14、scrollBeyondLastLine: false、renderWhitespace: 'selection'、minimap.enabled: false. Die Minimap ist deaktiviert, weil Template und Artefakt normalerweise nur ein paar Dutzend Zeilen haben und die Minimap eher horizontalen Platz belegt.

Step-by-Step Walkthrough

Szenario: Der Benutzer öffnet die Seite, gibt<div>{{ msg }}</div>ein und bewegt dann den Cursor.

Erster Schritt: Initialisierung und Zustandswiederherstellung. window.initIst der globale Einstiegspunkt📎 packages-private/template-explorer/src/index.ts:41. Er registriert und aktiviert zuerst das benutzerdefinierte Theme📎 packages-private/template-explorer/src/index.ts:44-45, und versucht dann, den Zustand aus dem URL-Hash oder localStorage wiederherzustellen📎 packages-private/template-explorer/src/index.ts:49-56. Beachte hier die Dekodierungsreihenfolge: zuerstatob, dannescape, danndecodeURIComponent. Wenn das Hash-Parsing fehlschlägt, wird auflocalStorage.getItem('state')zurückgefallen, dann auf{}. Wenn das gesamte JSON.parse fehlschlägt, wird localStorage geleert und eine Warnung ausgegeben📎 packages-private/template-explorer/src/index.ts:57-64。

Nach der Zustandswiederherstellung gibt es ein leicht zu übersehendes Detail:delete persistedState.options?.nodeTransforms 📎 packages-private/template-explorer/src/index.ts:69. Der Kommentar erklärt den Grund – Funktionen können nicht serialisiert werden, daher geht beim PersistierennodeTransformsverloren; wenn bei der Wiederherstellung ein leeres Objekt zurückbleibt, führt das zu anormalem Compiler-Verhalten. Dies ist die klassische Falle beim „Persistieren nicht serialisierbarer Felder“.

Zweiter Schritt: KompilierungskerncompileCode。Dies ist das Herz des gesamten Tools📎 packages-private/template-explorer/src/index.ts:76-106. Er macht zuerstconsole.clear(), wählt dann abhängig vonssrMode.valuessrCompileodercompile 📎 packages-private/template-explorer/src/index.ts:80. Beachte die Aufrufparameter voncompileFn: Spread voncompilerOptions, erzwungenfilename: 'ExampleTemplate.vue'、sourceMap: true, und Injektion desonError-Callbacks zum Sammeln von Fehlern📎 packages-private/template-explorer/src/index.ts:82-89。

Hier gibt es eine Designentscheidung:filenameist hartcodiert auf'ExampleTemplate.vue'. Dieser Wert muss in den späterengeneratedPositionFor-Aufrufen exakt übereinstimmen mit📎 packages-private/template-explorer/src/index.ts:189, sonst liefert die SourceMap-Abfrage ein leeres Ergebnis. Dies ist ein impliziter Vertrag – die beiden Strings müssen übereinstimmen, aber kein Typsystem garantiert das.

Nach Abschluss der Kompilierung werden Fehler in das Marker-Format von Monaco umgewandelt und im Editor gesetzt📎 packages-private/template-explorer/src/index.ts:91-95。formatErrorwandeltCompilerErrorvonlocin MonacosstartLineNumber/startColumn/endLineNumber/endColumn 📎 packages-private/template-explorer/src/index.ts:108-119um. Beachteerrors.filter(e => e.loc)– nur Fehler mit Positionsinformationen werden markiert; Fehler ohneloc(wie globale Konfigurationsfehler) werden nur in der Konsole ausgegeben.

Dritter Schritt: Aufbau der SourceMap.Nach erfolgreicher Kompilierung,lastSuccessfulMap = new SourceMapConsumer(map!) 📎 packages-private/template-explorer/src/index.ts:99, und unmittelbar danach wirdcomputeColumnSpans() 📎 packages-private/template-explorer/src/index.ts:100。computeColumnSpansaufgerufen. Ist eine entscheidende API vonsource-map-js: Sie berechnet die Spaltenbreite jedes Mapping-Segments vorab, sodassgeneratedPositionFordaslastColumn-Feld zurückgibt, das verwendbar ist. Ohne diesen Schritt kann die Rückwärtszuordnung nur die Startspalte lokalisieren und nicht den gesamten Token-Bereich hervorheben.

Vierter Schritt: Bidirektionale Cursor-Zuordnung.Wenn der Benutzer imQuellcode-Editorden Cursor bewegt, wirdeditor.onDidChangeCursorPosition 📎 packages-private/template-explorer/src/index.ts:184ausgelöst. Der Callback ruft nach 100 ms DebouncelastSuccessfulMap.generatedPositionFor({ source: 'ExampleTemplate.vue', line, column: column - 1 }) 📎 packages-private/template-explorer/src/index.ts:188-192auf. Beachtecolumn - 1: Monacos Spaltennummern beginnen bei 1, während die Spaltennummern der SourceMap bei 0 beginnen. Das zurückgegebenepos, falls eslineundcolumnhat, erzeugt im Ausgabe-Editor einen Decorator, der den entsprechenden Bereich hervorhebt📎 packages-private/template-explorer/src/index.ts:194-206, und scrollt zu dieser Position📎 packages-private/template-explorer/src/index.ts:207-210。

Die Rückwärtszuordnung erfolgt inoutput.onDidChangeCursorPosition📎 packages-private/template-explorer/src/index.ts:223. Sie ruftoriginalPositionFor 📎 packages-private/template-explorer/src/index.ts:227-230auf, hat aber eine zusätzliche Guard: Ignoriertpos.line === 1 && pos.column === 0„mock location“📎 packages-private/template-explorer/src/index.ts:231-237. Dieser Guard ist entscheidend – bestimmter vom Compiler generierter Code (wieimportAnweisungen oder Helper-Funktionen) hat keine entsprechende Template-Position, und SourceMap gibt{ line: 1, column: 0 }als Platzhalter zurück. Wenn dies nicht ignoriert wird, führt ein Cursor auf diesen Zeilen fälschlicherweise dazu, dass die erste Zeile des Templates hervorgehoben wird.

Fünfter Schritt: Zustandspersistenz. reCompilelöst nicht nur die Kompilierung aus, sondern ist auch dafür verantwortlich, den aktuellen Zustand in localStorage und URL-Hash zu schreiben📎 packages-private/template-explorer/src/index.ts:121-146. Bei der Persistenz gibt es eine Trim-Logik: Durchlaufen voncompilerOptions, wobei nur Einträge gespeichert werden, die „kein Objekt sind und nicht dem Standardwert entsprechen“📎 packages-private/template-explorer/src/index.ts:125-133. Das erklärt, warumbindingMetadataOptionen dieses Objekttyps nicht persistiert werden – es ist zu komplex, und der Standardwert reicht bereits zur Demonstration aus.

flowchart TD
    init["window.init()"] --> restore{"hash 或 localStorage 有状态?"}
    restore -->|是| parse["JSON.parse 成功?"]
    restore -->|否| useDefault["使用默认模板"]
    parse -->|成功| delNodeTrans["delete nodeTransforms"]
    parse -->|失败| clearLS["localStorage.clear() + 警告"]
    delNodeTrans --> createEditor["monaco.editor.create(source)"]
    clearLS --> createEditor
    useDefault --> createEditor
    createEditor --> initOpt["initOptions()"]
    initOpt --> watch["watchEffect(reCompile)"]
    watch --> compileCode["compileCode(source)"]
    compileCode --> chooseFn{"ssrMode.value?"}
    chooseFn -->|true| ssr["ssrCompile(source, opts)"]
    chooseFn -->|false| dom["compile(source, opts)"]
    ssr --> hasMap{"map 存在?"}
    dom --> hasMap
    hasMap -->|是| newSMC["new SourceMapConsumer(map)"]
    hasMap -->|否| skipMap["lastSuccessfulMap 保持 undefined"]
    newSMC --> computeSpan["computeColumnSpans()"]
    computeSpan --> setOutput["output.setValue(code)"]
    skipMap --> setOutput
    compileCode -->|抛异常| catchErr["lastSuccessfulCode = ERROR 注释"]
    catchErr --> setOutput

Designüberlegungen und Stolperfallen im Produktivbetrieb

Warumsource-map-jsstattsource-map？ source-mapist die Originalbibliothek von Mozilla, groß und abhängig von WASM (in der neuen Version).source-map-jsist eine reine JS-Implementierung, klein und für Browser-Umgebungen geeignet. Da Template Explorer ein reines Frontend-Tool ist, ist die Wahl vonsource-map-jssinnvoll📎 packages-private/template-explorer/package.json:15。

Wahl der debounce-Verzögerung.Der Standard-debounce des Quellcode-Editors beträgt 300 ms📎 packages-private/template-explorer/src/index.ts:271, während der debounce für Cursorbewegungen 100 ms beträgt📎 packages-private/template-explorer/src/index.ts:215. Dieser Unterschied ist beabsichtigt: Kompilierung ist eine schwere Operation, 300 ms vermeiden häufige Auslösungen; Cursorbewegung ist eine leichte Operation, 100 ms gewährleisten Reaktionsfähigkeit. Aber 100 ms können bei schneller Cursorbewegung immer noch zu Flackern der Hervorhebung führen – ein akzeptabler Kompromiss.

window.initGlobales Mounting vonBeachten Sie, dasswindow.initundwindow.monacobeide global an📎 packages-private/template-explorer/src/index.ts:19-23gehängt werden. Der Grund ist, dass der Monaco-Editor über das CDNloader.jsasynchron geladen wird und nach Abschluss des Ladenswindow.initaufruft. Dieses „globale Callback“-Muster ist die Standardverwendung von Monaco in einer nicht-modularen Umgebung, passt aber schlecht zu modernen ESM-Build-Ansätzen.

---

Zwei: reactive-gesteuertes Optionspanel: options.ts

Intuitives Modell

options.tsEs ist wie ein „Konsolenpanel“: Oben gibt es ein Dutzend Schalter und Radiobuttons, von denen jeder einem Verhalten des Compilers entspricht. Wird ein beliebiger Schalter umgelegt, ändert sich das Kompilierungsergebnis rechts sofort. Ohne dieses Modul könnten Entwickler nur diecompileAufrufparameter im Quellcode ändern und neu kompilieren, ohne die Wirkung verschiedener Optionen in Echtzeit vergleichen zu können.

Datenstruktur und Speicherlayout

options.tsDer Kern von

ssrModesind drei Exporte:ref(false) 📎 packages-private/template-explorer/src/options.ts:5ist eincompilerOptions. Es ist unabhängig voncompile vs ssrCompile, weil der SSR-Modus die Kompilierungsfunktion selbst umschaltet (

defaultOptions), nicht die Kompilierungsoptionen.CompilerOptionsist ein vollständiges📎 packages-private/template-explorer/src/options.ts:5-27Objektmode: 'module'、prefixIdentifiers: false、hoistStatic: false、cacheHandlers: false、scopeId: null、inline: false、ssrCssVars: '{ color }'、compatConfig: { MODE: 3 }、whitespace: 'condense'. Es definiert die Standardwerte aller Optionen, einschließlichbindingMetadata 📎 packages-private/template-explorer/src/options.ts:18-26。

compilerOptions, sowie einesreactive(Object.assign({}, defaultOptions)) 📎 packages-private/template-explorer/src/options.ts:29-31mit 7 Bindungstypen.Object.assign({}, ...)istreactive(defaultOptions). Beachten Sie, dass hiercompilerOptionsfür eine flache Kopie verwendet wird – bei direktemdefaultOptionswürde eine Änderung vonreCompileden Wert von

Step-by-Step Walkthrough

verunreinigen und die Logik „Vergleich mit Standardwert“ in

ungültig machen. AppSzenario: Der Benutzer klickt auf das Kontrollkästchen „hoistStatic“.setupErster Schritt: UI-Rendering.📎 packages-private/template-explorer/src/options.ts:33-35DiessrMode.value、compilerOptions.mode、compilerOptions.prefixIdentifiers-Methode der📎 packages-private/template-explorer/src/options.ts:36-39-Komponente gibt eine Renderfunktion

zurück. Diese Renderfunktion liest reaktive Zustände wie hoistStatic, daher wird die gesamte UI neu gerendert, wenn sich diese Zustände ändern.checkedZweiter Schritt: checked-Bindung des Kontrollkästchens.compilerOptions.hoistStatic && !isSSR 📎 packages-private/template-explorer/src/options.ts:150DashoistStatic-Attribut des Kontrollkästchens istdisabled: isSSR 📎 packages-private/template-explorer/src/options.ts:151. Hier gibt es eine Logik: Im SSR-Modus wird

zwangsweise als nicht ausgewählt angezeigt, da die SSR-Kompilierung statisches Hoisting nicht unterstützt. Gleichzeitig stelltsicher, dass der Benutzer es im SSR-Modus nicht umschalten kann.onChangeDritter Schritt: onChange-Behandlung.📎 packages-private/template-explorer/src/options.ts:152-156Wenn der Benutzer auf das Kontrollkästchen klickt, löste.target.checkedcompilerOptions.hoistStaticaus und weistcompilerOptionsdirektreactivezu. DawatchEffect(reCompile) 📎 packages-private/template-explorer/src/index.ts:266

ist, löst diese Zuweisung Dependency-Tracking aus, was wiederumauslöst und schließlich neu kompiliert.cacheHandlersVierter Schritt: Verknüpfung zwischen Optionen.checkedBeachten Sie, dassusePrefix && compilerOptions.cacheHandlers && !isSSR 📎 packages-private/template-explorer/src/options.ts:166，disabledvon!usePrefix || isSSR 📎 packages-private/template-explorer/src/options.ts:167cacheHandlersistprefixIdentifiersistmode === 'module'. Das bedeutet, dassprefixIdentifiersvonfunctionodercacheHandlersabhängt. Diese Verknüpfung zeigt sich in der UI so: Wenn

scopeIdnicht aktiviert ist und der Modusdisabled: !isModule 📎 packages-private/template-explorer/src/options.ts:182，checked: isModule && compilerOptions.scopeId 📎 packages-private/template-explorer/src/options.ts:183ist, ist das KontrollkästchenisModuledeaktiviert.null 📎 packages-private/template-explorer/src/options.ts:184-189。

Die Verknüpfung von initOptionsist komplexer:createApp(App).mount(document.getElementById('header')!) 📎 packages-private/template-explorer/src/options.ts:232-234. Nur im module-Modus kann scopeId gesetzt werden, und bei onChange wird, wennvuefalse ist, zwangsweisecreateAppgesetzt. Fünfter Schritt: Mounting.@vue/runtime-domruftoptions.tsauf. Beachten Sie, dass hiervueaus dem

flowchart LR
    subgraph reactive_state["reactive 状态层"]
        ssrMode["ssrMode: Ref<boolean>"]
        compilerOptions["compilerOptions: reactive(CompilerOptions)"]
    end
    subgraph ui_layer["UI 渲染层 (options.ts)"]
        modeRadio["mode 单选"]
        wsRadio["whitespace 单选"]
        ssrCheck["SSR 复选框"]
        prefixCheck["prefixIdentifiers 复选框"]
        hoistCheck["hoistStatic 复选框"]
        cacheCheck["cacheHandlers 复选框"]
        scopeCheck["scopeId 复选框"]
        inlineCheck["inline 复选框"]
        compatCheck["compatConfig 复选框"]
    end
    subgraph compile_layer["编译层 (index.ts)"]
        watchEffect["watchEffect(reCompile)"]
        compileCode["compileCode()"]
    end
    ssrMode -->|"checked/disabled"| ssrCheck
    ssrMode -->|"isSSR 守卫"| hoistCheck
    ssrMode -->|"isSSR 守卫"| cacheCheck
    compilerOptions -->|"mode"| modeRadio
    compilerOptions -->|"whitespace"| wsRadio
    compilerOptions -->|"prefixIdentifiers"| prefixCheck
    compilerOptions -->|"hoistStatic"| hoistCheck
    compilerOptions -->|"cacheHandlers"| cacheCheck
    compilerOptions -->|"scopeId"| scopeCheck
    compilerOptions -->|"inline"| inlineCheck
    compilerOptions -->|"compatConfig.MODE"| compatCheck
    modeRadio -->|"onChange 赋值"| compilerOptions
    wsRadio -->|"onChange 赋值"| compilerOptions
    ssrCheck -->|"onChange 赋值"| ssrMode
    prefixCheck -->|"onChange 赋值"| compilerOptions
    hoistCheck -->|"onChange 赋值"| compilerOptions
    cacheCheck -->|"onChange 赋值"| compilerOptions
    scopeCheck -->|"onChange 赋值"| compilerOptions
    inlineCheck -->|"onChange 赋值"| compilerOptions
    compatCheck -->|"onChange 赋值"| compilerOptions
    compilerOptions -->|"依赖追踪"| watchEffect
    ssrMode -->|"依赖追踪"| watchEffect
    watchEffect --> compileCode

– weil

Anwendungscode ist und direkt vom vollständigenreactive-Paket abhängen kann.ref？ compilerOptionsKopierenreactiveDesignüberlegungen und Stolperfallen im ProduktivbetriebcompilerOptions.hoistStatic = trueWarumcompilerOptions.value.hoistStatic = truestattreactiveverwendet wird:compilerOptions.xxxist ein Objekt mit einem Dutzend Feldern; mit

bindingMetadatakann direktverwendet werden, ohne📎 packages-private/template-explorer/src/options.ts:18-26. Das ist im UI-Code prägnanter. Aber der Preis vonSETUP_CONST、SETUP_REF、SETUP_LET、SETUP_MAYBE_REF、PROPSist, dass Destrukturierung die Reaktivität verliert – im Quellcode gibt es keine Destrukturierung, alles wird überprefixIdentifierszugegriffen, was die korrekte Verwendung ist.$setupDesign der Standardwerte vonprefixIdentifiers. Die Standardwerte von

compatConfigenthalten 7 Bindungen compilerOptions.compatConfig!.MODE = 2 📎 packages-private/template-explorer/src/options.ts:216-220und decken die fünf Typenreactiveab. Dies soll Entwicklern ermöglichen, nach dem Öffnen vonreactivesofort die Auswirkungen verschiedener Bindungstypen auf diecompatConfigZugriffsmethoden im Ergebnis zu sehen. Ohne diesen Standardwert wäre der Effekt vonCompatConfig | undefinedsehr monoton.!Verschachtelte Reaktivität voncompatConfig. Eine solche verschachtelte Zuweisung ist unter

ssrModereaktiv, weilcompilerOptionsverschachtelte Objekte rekursiv proxyt. Beachten Sie jedoch, dass der Typ von ssrModeref，compilerOptionsist, daher wird einereactiveAssertion verwendet. Wennssrnicht in den Standardwerten enthalten wäre, würde dies hier zur Laufzeit abstürzen.compilerOptionsTrennung der Zuständigkeiten vonssrundCompilerOptions.

---

ist

ist

theme.tsWie ein „Skin-Wechsel" für den Editor: Es definiert Farbe und Schriftstil für jeden Syntax-Token. Ohne dieses Modul verwendet Monaco das Standard-vs-darkTheme. Es funktioniert zwar, aber HTML-Tags, Ausdrücke und Direktiven in Vue-Templates sind visuell nicht unterscheidbar, sodass Entwickler wichtige Teile nicht schnell finden können.

Datenstruktur und Speicherlayout

theme.tsExportiert ein Objekt, das der Monaco-IStandaloneThemeDataSchnittstelle entspricht📎 packages-private/template-explorer/src/theme.ts:1-244. Es hat drei Top-Level-Felder:

base: 'vs-dark'Gibt das Basistheme an📎 packages-private/template-explorer/src/theme.ts:2，inherit: trueStellt Regeln dar, die vom Basistheme erben📎 packages-private/template-explorer/src/theme.ts:3. Das bedeutet, dass nur die Unterschiede definiert werden müssen; nicht definierte Tokens fallen zurück aufvs-dark。

rulesIst ein Array, jedes Element enthälttoken(Monacos Token-Name) undforeground/background/fontStyle 📎 packages-private/template-explorer/src/theme.ts:4-235. Dieses Array hat über 50 Einträge und deckt Token-Typen wie number, comment, keyword, string, variable, entity.name.tag usw. ab.

colorsDefiniert die Farben der Editor-UI📎 packages-private/template-explorer/src/theme.ts:236-243：editor.foreground、editor.background、editor.selectionBackground、editor.lineHighlightBackground、editorCursor.foreground、editorWhitespace.foreground。

Step-by-Step Walkthrough

Szenario: Theme beim Laden der Seite registrieren.

Schritt 1: Theme definieren. monaco.editor.defineTheme('my-theme', theme) 📎 packages-private/template-explorer/src/index.ts:44. Dieser Aufruf registrierttheme.tsdas exportierte Objekt im Theme-Register von Monaco unter dem Schlüsselnamen'my-theme'。

Schritt 2: Theme aktivieren. monaco.editor.setTheme('my-theme') 📎 packages-private/template-explorer/src/index.ts:45. Diese Codezeile muss nachdefineThemeaufgerufen werden, sonst wird der Fehler „Theme nicht definiert" ausgelöst.

Schritt 3: Token-Matching.Wenn Monaco Template-Code rendert, tokenisiert es den Code mit dem HTML Language Service und sucht dann anhand des Token-Namens nach Regeln inrules. Zum Beispiel<div>indivwird markiert alsentity.name.tag, passt zuforeground: 'cc6666' 📎 packages-private/template-explorer/src/theme.ts:41-44, wird rot angezeigt.

Designüberlegungen und Stolperfallen im Produktivbetrieb

Waruminherit: true？verwenden? Ohne Vererbung müssten die Farben aller Tokens definiert werden, einschließlich derer, die im Template nicht vorkommen (wiemarkup.heading、meta.diff). Vererbung ermöglicht es, in der Theme-Datei nur die Tokens zu berücksichtigen, die tatsächlich im Template und im JS-Ergebnis vorkommen.

Hierarchisches Matching von Token-Namen.Monacos Token-Matching erfolgt per Präfix-Matching:entity.name.tagpasst zuentity.name.tag.html、entity.name.tag.cssusw. Im Quellcode werden sowohlentity.name.tag 📎 packages-private/template-explorer/src/theme.ts:41-44als auchentity.name.tag.css 📎 packages-private/template-explorer/src/theme.ts:169-172definiert; Letzteres überschreibt Ersteres im CSS-spezifischen Szenario.

colorsArbeitsteilung zwischenrulesund rules.colorssteuert die Farbe des Code-Textes,editor.background: '#1D1F21'steuert die Farben der Editor-UI (Hintergrund, Cursor, ausgewählte Zeile). Beide sind unabhängig, müssen aber visuell aufeinander abgestimmt sein. Im Quellcode sindbase: 'vs-dark'und

---

die Standardhintergründe ähnlich, um visuelle Konsistenz zu wahren.

Designüberlegung: Engineering-Abwägungen bei visuellen Sonden

Der Kernunterschied zwischen Template Explorer und SFC Playground liegt in der „Beobachtungsgranularität". Der Playground beobachtet, „ob ein gesamtes SFC nach der Kompilierung ausgeführt werden kann"; der Template Explorer beobachtet, „zu was ein einzelner Template-Ausdruck kompiliert wird". Dieser Unterschied bestimmt die technische Auswahl der beiden Tools:Die Einführung von SourceMapConsumer ist unvermeidlich.source-map-jsOhne es könnten Entwickler Quellcode und Ergebnis nur mit bloßem Auge vergleichen und keine präzise Zuordnung „Zeile X → Zeile Y" herstellen. Die API von SourceMapConsumer ist jedoch asynchron (neuere Versionen geben ein Promise zurück); im Quellcode wird die synchrone Version verwendet

reactive, um die Aufruflogik zu vereinfachen.Verwaltungsoptionen sind die natürliche Wahl im Vue-Ökosystem.reactiveWenn der Status von über einem Dutzend Optionen mit nativen DOM-Events manuell synchronisiert würde, würde sich die Codemenge verdoppeln.watchEffect(reCompile)Die Abhängigkeitsverfolgung von

automatisiert die Kette „Optionsänderung → Neukompilierung"; window.monacoeine Codezeile erledigt das Abonnieren.window.initMonacos globales Lademodell ist historischer Ballast.

---

Die globale Einbindung von

undindex.tsstammt aus dem AMD-Loader-Design von Monaco. In modernen ESM-Builds wirkt das fehl am Platz, aber Monacos Größe (ca. 5 MB) macht bedarfsgerechtes Laden weiterhin erforderlich.compileCodeZusammenfassung dieses Kapitels@vue/compiler-domTemplate Explorer ist eine „White-Box-Sonde": Er führt das Kompilierungsergebnis nicht aus, sondern zeigt nur den Kompilierungsprozess.@vue/compiler-ssrDurchSourceMapConsumerwirdoptions.tsoderreactiveaufgerufen, mitCompilerOptionseine bidirektionale Zuordnung zwischen Quellcode und Ergebnis hergestellt und über Monacos Decorator-API eine synchronisierte Cursor-Hervorhebung umgesetzt.watchEffectMithoistStaticwirdtheme.tsverwaltet, über

die Neukompilierung angesteuert, und die Verknüpfungen zwischen Optionen (z. B. SSR deaktivierthoistStatic) werden explizit in der UI-Schicht codiert.

Ein benutzerdefiniertes Monaco-Theme sorgt für eine klare visuelle Unterscheidung der Syntax-Tokens von Template und Ergebnis.

---

Das nächste Kapitel führt inscripts/release.jsein und zeigt, wie Vue mit einem interaktiven Zustandsautomaten den gesamten Ablauf von Versionsnummernaktualisierung, Build, Test, Git-Commit, Tagging und npm publish orchestriert. Anders als das „Beobachten“ des Template Explorers ist release.js „Ausführen“ – es muss den Zustand über mehrere Schritte hinweg pflegen, Fehler-Rollbacks behandeln und ein Gleichgewicht zwischen interaktiver Bestätigung und Automatisierung finden.

Durch den Template Explorer haben wir gelernt, wie der interne Compiler-Zustand – AST, Kompilierungsartefakte, SourceMap – in interaktive visuelle Sonden umgewandelt werden kann, wodurch „warum der Compiler dies so generiert“ von Vermutung zu Beobachtung wird. Diese präzise Kontrolle und Orchestrierung des internen Zustands zeigt sich ebenso im Vue-Release-Prozess: Das nächste Kapitel taucht tief in scripts/release.js ein und zeigt, wie ein über 500 Zeilen langer Zustandsautomat mit parseArgs über ein Dutzend Flags parst, über enquirer interaktiv die Versionsnummer bestätigt und der Reihe nach Build, Test, Git-Commit, Tagging und npm publish auslöst, und enthüllt den vollständigen Zustandsfluss und die Fehler-Rollback-Strategie hinter einem offiziellen Release.

Im vorherigen Kapitel haben wir mithilfe des template-explorers das Compiler-Verhalten zurückverfolgt und die Methodik erlernt, interne Mechanismen mit Werkzeugen zu beobachten. Jetzt richten wir unseren Blick von der Kompilierungszeit auf die Release-Zeit – dies ist der gefährlichste Moment jedes Open-Source-Projekts: Er berührt gleichzeitig vier irreversible externe Systeme: Versionsnummer, Build-Artefakte, Git-Historie und npm registry. Ein fehlerhaftes npm publish kann nicht zurückgenommen werden, ein fehlerhaft gepushter Tag verunreinigt die Abhängigkeitsauflösung aller nachgelagerten Benutzer. Vue core verwendet ein 537 Zeilen langes scripts/release.js, um diese Gefahr zu bändigen – es ist weder ein reines Automatisierungsskript noch eine reine manuelle Checkliste, sondern ein interaktiver Zustandsautomat: An kritischen Knoten wird angehalten und gefragt, an vorhersehbaren Knoten vollautomatisch ausgeführt, und bei einem Fehler in irgendeinem Schritt wird die Versionsnummer auf den Ausgangspunkt zurückgerollt. Dieses Kapitel zerlegt die drei Kernmechanismen dieses Orchestrators: Argumentanalyse und Zustandsinitialisierung, interaktive Versionsentscheidung und CI-Gate, sowie Release-Reihenfolge und Fehler-Rollback.

Argumentanalyse und globale Zustandsinitialisierung

Intuitives Modell

Stellen Sie sichrelease.jsals Bedienfeld einer alten Waschmaschine vor: Der Drehknopf (parseArgsSpeicherlayout von Flags und globalem Zustand

标志位与全局状态的内存布局

📎 scripts/release.js:27-62definiert 10 Optionen, die in vier Kategorien unterteilt werden können:

• Versionssemantik-Kategorie：preid(Pre-Release-Identifikator, wiealpha/beta/rc）、tag（npm dist-tag）
• Überspringen-Kategorie：skipBuild、skipTests、skipGit、skipPrompts– diese vier booleschen Schalter bilden den „Automatisierungsgrad“-Regler
• Ausführungsmodus-Kategorie：dry(Leerlauf),publish(ob lokal direkt veröffentlicht wird),publishOnly(nur veröffentlichen, Version nicht aktualisieren)
• Ziel-Kategorie：registry(benutzerdefinierte Registry-Adresse)

Beachten Sie, dass der Standardwert vonpublishfalse 📎 scripts/release.js:51-54ist, während andere boolesche Elemente keinen Standardwert haben (d. h.undefined). Diese Asymmetrie ist beabsichtigt:publishDie Semantik vonskipXxxist „ob npm publish lokal ausgeführt wird“, standardmäßig nicht veröffentlichen, die Veröffentlichungsaktion wird an GitHub Actions übergeben; währendundefinedstandardmäßig--skipTestsbedeutet „nicht angegeben“, die nachfolgende Logik wird unterscheiden zwischen „Benutzer hat explizit

übergeben“ und „Benutzer hat nicht übergeben“.📎 scripts/release.js:64-66：

const preId = args.preid || semver.prerelease(currentVersion)?.[0]
const isDryRun = args.dry
let skipTests = args.skipTests
const skipBuild = args.skipBuild
const skipPrompts = args.skipPrompts
const skipGit = args.skipGit

KopierenpreIdHier gibt es zwei bemerkenswerte Designentscheidungen. Erstens, die Wertepriorität von📎 scripts/release.js:64-66ist „explizite Angabe auf der Kommandozeile > Ableitung aus der aktuellen Versionsnummer“package.json. Wenn die aktuelle Version von3.5.0-beta.1semver.prereleaseist, dann gibt['beta', 1][0]zurück, nimmt'beta'und erhält--preid beta. Das bedeutet, dass beim kontinuierlichen Veröffentlichen auf dem Beta-Branch nicht jedes MalskipTestseingegeben werden muss. Zweitens,letwird mitconst 📎 scripts/release.js:64-66deklariert, während andererunTestsIfNeededverwenden, weil es in

dynamisch durch CI-Ergebnisse überschrieben wird – dies ist ein „verzögerte Entscheidung“-Statusbit.📎 scripts/release.js:68-83Als Nächstes folgt die Paket-Erkennungslogikpackages/: Lesen despackage.jsonVerzeichnisses, Herausfiltern von Nicht-Verzeichnis-Einträgen, Einträgen ohneprivate: trueund Paketen mitpackages/. Beachten Sie, dass hierpackages-private/gelesen wird, nicht

– letzteres ist ein internes Debug-Paket, das niemals veröffentlicht wird.

📎 scripts/release.js:85-85Der Sortieralgorithmus für die Veröffentlichungsreihenfolge

const sortPackagesForPublishing = (packageNames) => [
  ...packageNames.filter(p => p !== 'vue'),
  ...packageNames.filter(p => p === 'vue'),
]

KopierenvueEs platziert das Einstiegspaket📎 scripts/release.js:85-85an das Ende. Der Kommentarvueerklärt den Grund: Wenn zuerst@vue/runtime-coreveröffentlicht wird, können Benutzer eine neue Version vonvueinstallieren, bevor interne Pakete wie

online sind, und npm wird einen Fehler melden, weil keine passende interne Abhängigkeit gefunden wird. Dies ist ein Kompromiss für „Veröffentlichungsatomizität“ im npm-Ökosystem – npm hat keine paketübergreifenden Transaktionen und kann Atomizität nur durch Reihenfolge annähern.

📎 scripts/release.js:111-116Dynamische Konstruktion der Versionsinkrement-Kandidatenmenge

const versionIncrements = [
  'patch', 'minor', 'major',
  ...(preId ? ['prepatch', 'preminor', 'premajor', 'prerelease'] : []),
]

KopierenpreIdDies ist eine bedingte Erweiterung: Nur wenn--preidexistiert (d. h. derzeit im Pre-Release-Kanal oder der Benutzer hat explizit3.5.43angegeben), werden die Pre-Release-bezogenen Inkrementtypen zum Menü hinzugefügt. Wenn derzeit eine stabile Versionpreidund keinpatch/minor/majorangegeben ist, hat das Menü nur die drei Einträge3.5.44-0– um zu vermeiden, dass der Benutzer durch Fehlbedienung die stabile Version in eine halbherzige Pre-Release-Version wie

incverwandelt.📎 scripts/release.js:120-120Die Funktionsemver.inckapseltpreIdund übergibttypeof preId === 'string' ? preId : undefinedals dritten Parameter. Hier gibt es eine Typverteidigung:preId– weilstring | undefinedmöglicherweisesemver.incist, währendstring | undefined

erwartet, dient dieser Ternärausdruck der Erfüllung der TS-Typverengung.

📎 scripts/release.js:122-123Ausführungsprimitive: Das Dual-Track-System von run und dryRun

const run = async (bin, args, opts = {}) =>
  exec(bin, args, { stdio: 'inherit', ...opts })
const dryRun = async (bin, args, opts = {}) =>
  console.log(pico.blue(`[dryrun] ${bin} ${args.join(' ')}`), opts)
const runIfNotDry = isDryRun ? dryRun : run

runKopiereninheritsetzt das stdio des Unterprozesses aufdryRun, sodass die Ausgabe von Build/Tests direkt an das Terminal weitergeleitet wird – dies ist entscheidend für lang laufende Builds, der Benutzer kann den Fortschritt in Echtzeit sehen.runIfNotDrygibt nur den Befehl aus, ohne ihn auszuführen.dryRunist eine „Strategieauswahl“: Beim Laden des Moduls wird der Funktionszeiger anrunoderisDryRun。

flowchart TD
    start["node scripts/release.js"] --> parse["parseArgs 解析 10 个选项"]
    parse --> preid{"args.preid 存在?"}
    preid -->|是| use_arg["preId = args.preid"]
    preid -->|否| infer["preId = semver.prerelease(currentVersion)[0]"]
    use_arg --> scan["扫描 packages/ 目录"]
    infer --> scan
    scan --> filter{"是目录 且 有 package.json 且 非 private?"}
    filter -->|否| skip_pkg["排除该包"]
    filter -->|是| keep_pkg["加入 packages 列表"]
    skip_pkg --> build_menu
    keep_pkg --> build_menu
    build_menu{"preId 存在?"} -->|是| full["versionIncrements = patch/minor/major + 4 个 pre*"]
    build_menu -->|否| stable["versionIncrements = patch/minor/major"]
    full --> dispatch{"args.publishOnly?"}
    stable --> dispatch
    dispatch -->|是| publish_only["fnToRun = publishOnly"]
    dispatch -->|否| main_fn["fnToRun = main"]

---

Kopieren

Interaktive Versionsentscheidung und CI-Gate

Intuitives Modell

Diese Phase ist wie eine Flughafensicherheitskontrolle: Zuerst wird Ihr Boarding-Pass überprüft (ob der lokale Commit mit dem Remote synchronisiert ist), dann wird bestätigt, wohin Sie wollen (Versionsnummer), und schließlich wird geprüft, ob Sie die Sicherheitskontrolle bestanden haben (ob CI bestanden wurde). Wenn eine dieser Prüfungen fehlschlägt, wird der gesamte Prozess abgebrochen. Ohne dieses Gate könnte ein nicht gepushter lokaler Commit getaggt und veröffentlicht werden, sodass der Quellcode, der der Version auf npm entspricht, auf GitHub überhaupt nicht existiert – dies ist der am schwersten zu diagnostizierende Veröffentlichungsunfall.

mainSynchronisationsprüfung und VersionsauswahlisInSyncWithRemote() 📎 scripts/release.js:141-141Das Erste, was die Funktion📎 scripts/release.js:337-363tut, istgit rev-parse HEAD. Die Logik dieser Funktion📎 scripts/release.js:348-355ist: den aktuellen Branch-Namen abrufen, die GitHub-API anfordern, um den neuesten Commit-SHA dieses Branches zu erhalten, und mit dem lokalenfalsevergleichen. Wenn sie nicht übereinstimmen, wird ein Bestätigungsdialog📎 scripts/release.js:365-367。

beendet 〔Design-Inferenz und Architektur-Abwägungen〕node scripts/release.js 3.6.0），targetVersionDie Designphilosophie hier ist „Fehler bedeutet Abbruch“: Bei Netzwerkausnahmen wird lieber nicht veröffentlicht, als das Risiko einzugehen, mit unbekanntem Status fortzufahren. Denn die Veröffentlichung ist irreversibel, während die Kosten für ein erneutes Ausführen des Skripts sehr gering sind.📎 scripts/release.js:141-141Die Bestimmung der Versionsnummer erfolgt über zwei Pfade. Wenn der Benutzer ein Positionsargument auf der Kommandozeile übergeben hat (wie📎 scripts/release.js:152-176wird direkt dieser Wert genommencustom. Andernfalls wird das interaktive Menü

aufgerufen: Zuerst wählt der Benutzer den Inkrementtyp, bei Auswahl von📎 scripts/release.js:174wird ein weiteres Eingabefeld angezeigt, in dem der Benutzer die Versionsnummer manuell eingeben kann.

targetVersion = release.match(/\((.*)\)/)?.[1] ?? ''

:patch (3.5.44)KopierencustomDas Format des Menüeintrags ist📎 scripts/release.js:164-172。

, diese Regex extrahiert die tatsächliche Versionsnummer aus den Klammern. Wenn der Benutzer📎 scripts/release.js:178-182gewählt hat, wird ein anderer ZweigtargetVersiondurchlaufen. Danach folgt eine „zweite Parsing“-Logikpatch/minorSolche inkrementellen Schlüsselwörter (der Benutzer könnte direkt übergebennode release.js minor), dann wirdincaufgerufen, um es in eine konkrete Versionsnummer umzuwandeln. Schließlich wird mitsemver.validvalidiert📎 scripts/release.js:184-186, ungültige Versionsnummern werfen direkt einen Fehler.

CI-Gate: Die dreistufige Logik von runTestsIfNeeded

Dies ist der komplexeste Kontrollfluss im gesamten Kapitel.📎 scripts/release.js:281-317DasrunTestsIfNeededist tatsächlich eine dreistufige Entscheidungsmaschine:

Zustand eins: Der Benutzer hat explizit--skipTests。skipTestsübergeben, initial auftruegesetzt, der gesamte Funktionskörper wird direkt übersprungen, "Tests skipped." wird ausgegeben📎 scripts/release.js:314-316。

Zustand zwei: Nicht übersprungen, und CI ist bereits bestanden. Das Skript ruftgetCIResult() 📎 scripts/release.js:319-335auf, es fragt die GitHub Actions API ab und prüft, ob ein Workflow-Run namenscimitconclusion === 'success'existiert📎 scripts/release.js:319-335. Falls bestanden, wird der Benutzer gefragt: „CI ist bestanden, lokale Tests überspringen?"📎 scripts/release.js:288-295. Falls der Benutzer--skipPromptsaktiviert hat, werden lokale Tests automatisch übersprungen📎 scripts/release.js:296-298。

Zustand drei: Nicht übersprungen, und CI ist nicht bestanden. Falls--skipPromptsaktiviert ist, wird direkt ein Fehler geworfen📎 scripts/release.js:299-304：

throw new Error(
  'CI for the latest commit has not passed yet. ' +
    'Only run the release workflow after the CI has passed.',
)

Falls nicht aktiviert--skipPrompts, dann bleibtskipTestsaufundefined, fällt in den letzten lokalen Test-Zweig📎 scripts/release.js:307-313, führtpnpm run test --run。

aus. Hier gibt es ein subtiles Detail📎 scripts/release.js:285：

skipTests ||= isCIPassed

||=ist eine logische Oder-Zuweisung: Nur wennskipTestsfalsy ist (undefinedoderfalse), wirdisCIPassedzugewiesen. Das bedeutet, wenn der Benutzer explizit--skipTests（trueübergeben hat), ändert diese Zeile nichts daran; wenn der Benutzer nichts übergeben hat (undefined), wird es auf das CI-Ergebnis gesetzt. Aber direkt danach wird📎 scripts/release.js:287-298bei bestandener CI erneut zugewiesen – also ist die tatsächliche Wirkung dieser Zeile||=nur „falls CI nicht bestanden, setzeskipTestsauffalse", wodurch der nachfolgendeif (!skipTests)-Zweig lokale Tests ausführt.

sequenceDiagram
    participant Dev as 开发者
    participant Main as main()
    participant Git as git CLI
    participant GH as GitHub API
    participant Pnpm as pnpm

    Dev->>Main: node scripts/release.js
    Main->>Git: getBranch() / getSha()
    Git-->>Main: branch, sha
    Main->>GH: fetch commits/{branch}
    GH-->>Main: remote sha
    alt sha 不一致
        Main->>Dev: prompt 确认继续?
        Dev-->>Main: yes/no
    end
    Main->>Dev: prompt 选择版本增量
    Dev-->>Main: "patch (3.5.44)"
    Main->>Main: semver.valid 校验
    Main->>GH: getCIResult() 查询 workflow_runs
    GH-->>Main: workflow_runs[]
    alt CI 通过
        Main->>Dev: prompt 跳过本地测试?
        Dev-->>Main: yes
    else CI 未通过
        Main->>Pnpm: run test --run
        Pnpm-->>Main: exit code
    end
    Main->>Main: updateVersions(targetVersion)

Versionsnummer schreiben: Die Iteration von updateVersions

📎 scripts/release.js:377-384DasupdateVersionsmacht zwei Dinge: die Root-package.jsonaktualisieren, dann alle Unterpakete durchlaufen undupdatePackage。updatePackage 📎 scripts/release.js:391-398aufrufen, um JSON zu lesen, dienameundversionumzuschreiben, mitJSON.stringify(pkg, null, 2) + '\n'zurückzuschreiben – beachten Sie das abschließende\n, dies dient dazu, die Datei mit einem Zeilenumbruch am Ende beizubehalten, um zu vermeiden, dass git diff „No newline at end of file" anzeigt.

getNewPackageNameDer ParameterkeepThePackageName 📎 scripts/release.js:105ist standardmäßig

---

, d.h. der Paketname wird nicht geändert. Dieser Parameter existiert, um das Szenario „Umbenennung des Pakets bei Veröffentlichung in einer benutzerdefinierten Registry" zu unterstützen – obwohl alle aktuellen Aufrufstellen den Standardwert übergeben, bietet die Schnittstelle Erweiterbarkeit.

Veröffentlichungsreihenfolge, Idempotenz und Fehler-Rollback

Intuitives ModellupdateVersionsDiese Phase ist wie Dominosteine:

Der erste Stein wird angestoßen (Versionsnummer ändern), die nachfolgenden changelog, lockfile, commit, tag, publish fallen nacheinander um. Wenn mittendrin ein Stein hängen bleibt, muss es einen Mechanismus geben, um die bereits umgefallenen Steine wieder aufzurichten – sonst bleibt das Repository im halbfertigen Zustand „Versionsnummer geändert, aber nicht veröffentlicht" stecken.

verwendet wird – weil die Versionsnummer die Form📎 scripts/release.js:453-458：

if (!isDryRun && (await isPackagePublished(packageName, version))) {
  console.log(pico.yellow(`Skipping already published: ${pkgVersion}`))
  alreadyPublishedPackages.push(pkgVersion)
  return
}

isPackagePublished 📎 scripts/release.js:491-513Vor der Veröffentlichung gibt es eine Idempotenzprüfungnpm view <pkg>@<version> versionKopierentrueführtfalseaus, bei Erfolg wird

zurückgegeben, bei einem E404-ähnlichen Fehler wirdnpm viewzurückgegeben. Der Sinn dieser Prüfung: Der Veröffentlichungsprozess könnte aufgrund von Netzwerkunterbrechungen erneut ausgeführt werden, bereits veröffentlichte Pakete sollten bei erneuter Ausführung nicht noch einmal veröffentlicht werden (npm lehnt doppelte Versionen ab).isPackagePublishedAber die Prüfung selbst kann auch fehlschlagen – zum Beispiel wirft📎 scripts/release.js:507-510aufgrund einer Netzwerk-Zeitüberschreitung einen Nicht-E404-Fehler. In diesem Fall wirft

den Fehler nach obenpnpm publish, was zum Abbruch der gesamten Veröffentlichung führt. Dies ist eine weitere Manifestation von „lieber abbrechen als Risiko eingehen".publishPackageSelbst wenn die Prüfung bestanden wird, kann📎 scripts/release.js:480-488：

} catch (e) {
  if (e.message?.match(/previously published/)) {
    console.log(pico.red(`Skipping already published: ${pkgVersion}`))
    alreadyPublishedPackages.push(pkgVersion)
  } else {
    throw e
  }
}

im catch-Block einen zweiten Fallback eingebautpreviously publishedKopieren

Nur wenn

📎 scripts/release.js:412-432übereinstimmt, wird der Fehler geschluckt, alle anderen Fehler werden erneut geworfen. Dies ist „präzise Fehlertoleranz": Nur bei bekannten, sicher ignorierbaren Fehlern wird eine Degradierung durchgeführt.pnpm publishDynamische Zusammensetzung der Veröffentlichungsflags

const additionalPublishFlags = []
if (isDryRun) additionalPublishFlags.push('--dry-run')
if (isDryRun || skipGit || process.env.CI)
  additionalPublishFlags.push('--no-git-checks')
if (process.env.CI && !args.registry)
  additionalPublishFlags.push('--provenance')

--no-git-checkssetzt je nach Laufzeitumgebung die zusätzlichen Flags fürpnpm publishzusammen:

--provenanceKopieren📎 scripts/release.js:425-427wird in drei Fällen aktiviert: dry run, git überspringen, oder in CI. Der Grund ist, dass!args.registrystandardmäßig prüft, ob der Arbeitsbereich sauber ist, ob der aktuelle Branch der Release-Branch ist usw., und in CI diese Prüfungen Fehlalarme auslösen.

wird nur in CI und wenn keine benutzerdefinierte Registry angegeben ist aktiviert

. Provenance ist eine Supply-Chain-Sicherheitsfunktion von npm, die die Herkunftsinformationen des Build-Artefakts (welcher Commit, welcher Workflow) signiert und an das Paket anhängt. Aber benutzerdefinierte Registries (wie interne private Registries) unterstützen Provenance normalerweise nicht, daher wurde die Bedingungmainhinzugefügt.📎 scripts/release.js:528-537：

fnToRun().catch(err => {
  if (versionUpdated) {
    updateVersions(currentVersion)
  }
  console.error(err)
  process.exit(1)
})

versionUpdatedZurück zum Ende vonfalse 📎 scripts/release.js:24-27KopierenupdateVersionsist eine boolesche Variable auf Modulebene, initialtrue 📎 scripts/release.js:208, wird sofort nach erfolgreichem Aufruf vontrueaufcurrentVersion。

Beachten SiepublishOnlyden Pfad📎 scripts/release.js:519-526wirdversionUpdatednicht gesetzt, da seine Semantik „nur veröffentlichen, keine Version ändern" lautet – selbst bei einem Fehler ist kein Rollback erforderlich. Wenn jedochtargetVersionexistiert, ruft esupdateVersions 📎 scripts/release.js:519-526auf; schlägt dies fehl, wird die Versionsnummer nicht zurückgerollt. Dies ist ein potenzielles Randproblem, siehe die Denkaufgabe am Ende des Kapitels.

flowchart TD
    upd["updateVersions(targetVersion)"] --> flag["versionUpdated = true"]
    flag --> changelog["pnpm run changelog"]
    changelog --> lock["pnpm install --prefer-offline"]
    lock --> gitdiff{"git diff 有输出?"}
    gitdiff -->|是| commit["git add -A && git commit"]
    gitdiff -->|否| nochange["No changes to commit"]
    commit --> pub{"args.publish?"}
    nochange --> pub
    pub -->|是| build["buildPackages()"]
    pub -->|否| push
    build --> publish["publishPackages()"]
    publish --> push["git tag && git push"]
    push --> done["完成"]
    changelog -.->|抛错| rollback["catch: updateVersions(currentVersion)"]
    lock -.->|抛错| rollback
    commit -.->|抛错| rollback
    publish -.->|抛错| rollback
    rollback --> exit["process.exit(1)"]

Veröffentlichungsreihenfolge und spezielle Behandlung des vue-Pakets

publishPackages 📎 scripts/release.js:412-432durchläuft die Ergebnisse vonsortPackagesForPublishing(packages)und ruft nacheinanderpublishPackageauf. Da die Sortierungvueans Ende setzt📎 scripts/release.js:85-85, stellt die gesamte Veröffentlichungssequenz sicher, dass interne Pakete zuerst online gehen.

publishPackageverwendet interncwd: getPkgRoot(pkgName) 📎 scripts/release.js:475, um das Arbeitsverzeichnis in das Unterpaketverzeichnis zu wechseln, sodasspnpm publishdas Unterpaket statt des Root-Pakets veröffentlicht. Der Kommentar📎 scripts/release.js:462-463warnt ausdrücklich: „Nicht zu npm publish ändern" – dennpnpm publishkann dasworkspace:*-Abhängigkeitsprotokoll korrekt verarbeiten und in eine tatsächliche Versionsnummer umwandeln, währendnpm publishdasworkspace:*unverändert beibehalten würde, was zu Installationsfehlern führt.

---

Designüberlegungen

WarumparseArgsstattyargs？verwenden? Das Veröffentlichungsskript ist die „letzte Verteidigungslinie" und muss in jeder Umgebung ausführbar sein. Wenn eine CLI-Bibliothek eines Drittanbieters aufgrund eines beschädigten Abhängigkeitsbaums nicht geladen werden kann, ist der gesamte Veröffentlichungsprozess lahmgelegt. Das in Node integrierteparseArgsist zwar funktional spartanisch (keine Subbefehle, keine automatische Hilfe), aber null Abhängigkeiten, null Risiko.

Warumpublishstandardmäßig auffalse？setzen? Weil die offizielle Veröffentlichung von Vue über GitHub Actions läuft (siehe Hinweis in📎 scripts/release.js:256-263), und das lokale Skript nur für Versionsänderung, Changelog-Generierung, Tag-Erstellung und Push zuständig ist. Das eigentlichenpm publishwird in der CI ausgeführt, um die Provenance-Signierung und kontrollierte Umgebung der CI zu nutzen.--publishDas

-Flag ist ein Notausgang für Maintainer, um im Notfall lokal zu veröffentlichen.Warum wird beim Rollback nur die Versionsnummer zurückgerollt?package.jsonWeil ein vollständiger Rollback verstehen müsste, „welche Änderungen vom Skript und welche vom Benutzer vorgenommen wurden", und dies auf Git-Ebene nicht unterschieden werden kann. Das Skript entscheidet sich, nur das zurückzurollen, bei dem es am sichersten weiß, dass es es geändert hat –

---

die Versionsnummer – und den Rest dem Benutzer zur Beurteilung zu überlassen.

scripts/release.jsKapitelzusammenfassung

1. implementiert mit 537 Zeilen Code eine „interaktive Zustandsmaschine", deren Kerndesign sich in drei Punkten zusammenfassen lässt:Parameter als StrategierunIfNotDry: 10 Flags werden beim Modulladen geparst und in globale Variablen abgeflacht,

2. bindet die Strategie bei der Initialisierung, um fehlende Prüfungen an Aufrufstellen zu vermeiden.Gatekeeping vorgelagert

3. : Synchronisationsprüfung, Versionsvalidierung und CI-Gate werden vor jeglichen Seiteneffekten abgeschlossen, um „alles oder nichts" sicherzustellen.：isPackagePublishedPräzise Fehlertoleranzpreviously publishedVorabprüfung +versionUpdatedFehler-Fallback bilden einen doppelten Idempotenzschutz;

Das Flag ermöglicht einen minimalen Rollback.Dieser Mechanismus bildet einen interessanten Kontrast zum Template Explorer aus dem vorherigen Kapitel: Template Explorer ist „Beobachten" – Visualisierung des internen Compiler-Zustands; release.js ist „Ausführen" – Explizierung jedes Schritts des Veröffentlichungsprozesses. Beide verkörpern dieselbe Ingenieursphilosophie:。

Impliziten Zustand in expliziten Zustand verwandeln, unkontrollierbare Seiteneffekte in kontrollierbare Schritte

---

Das nächste Kapitel führt in.github/workflows/ein und zeigt, wie GitHub Actions nach dem Push des Tags durch release.js die nachfolgende Build- und Release-Pipeline übernimmt sowie die vollständige Implementierung der CI-Gates.

Damit haben wir gesehen, wie release.js mit einer Zustandsmaschine und interaktiver Orchestrierung das irreversible Release-Risiko minimiert. Aber das Release-Skript selbst ist nur der Ausführende; wer wirklich entscheidet, wann ausgelöst wird und unter welchen Bedingungen freigegeben wird, ist der übergeordnete automatisierte Torwächter. Das nächste Kapitel analysiert das CI/CD-System im Verzeichnis .github/workflows: Wie ci.yml in der PR-Phase die dreifachen Gates lint/typecheck/test ausführt, wie release.yml beim Tag-Push das Release auslöst, wie size-report.yml und size-data.yml Paketgrößen-Regressionen verfolgen und wie autofix.yml Formatprobleme automatisch behebt. Du wirst verstehen, wie Vue mit GitHub Actions Engineering-Standards in eine nicht umgehbare Pipeline gießt.

Im vorherigen Kapitel haben wir gesehen, wiescripts/release.jsmit einer interaktiven Zustandsmaschine jeden Schritt eines Releases verkettet. Aber dieses Skript hat eine Voraussetzung: Es muss von einer Person oder einem System aktiv aufgerufen werden. Im Vue-core-Repository ist dieser aktive Aufrufer nicht das lokale Terminal eines Maintainers, sondern GitHub Actions. release.js ist der Ausführende, workflows sind der Entscheider – sie bestimmen, welches Ereignis welche Aufgabe auslöst, unter welchen Bedingungen freigegeben und unter welchen Bedingungen blockiert wird. Dieses Kapitel konzentriert sich auf.github/workflows/die vier Dateien im Verzeichnis:ci.yml(PR-Gate und kontinuierliche Vorabveröffentlichung),release.yml(tag-ausgelöste offizielle Veröffentlichung),size-report.yml(Bericht zu Größenregressionen),autofix.yml(automatische Formatkorrektur). Ihr Kern besteht nicht darin, YAML-Syntax auswendig zu lernen, sondern zu erkennen, wie das Vue-Team Engineering-Standards in nicht umgehbare Pipeline-Einschränkungen übersetzt.

I. ci.yml: Dreifache Gates und kontinuierliche Vorabveröffentlichung

Intuitives Modell

Stell dirci.ymlwie eine Flughafensicherheitskontrolle vor. Jeder PR muss durch dieses Gate: lint prüft, ob dein Gepäck verbotene Gegenstände enthält, typecheck bestätigt, dass dein Ausweis echt und gültig ist, test verifiziert, dass du keine Gefahrgüter mitführst. Aber es gibt nicht nur ein Sicherheitsgate – Vue hat hier auch einen „kontinuierlichen Vorabveröffentlichungs“-Kanal eingerichtet, der die Build-Artefakte jedes PR direkt auf pkg-pr-new veröffentlicht, damit Mitwirkende ihre Änderungen in einem echten npm-Installationsszenario validieren können.

Ohne dieses Gate könnte jede Zusammenführung Formatfehler, Typ-Lücken oder Verhaltensregressionen in den main-Branch bringen, und der main-Branch ist die Quelle aller nachfolgenden Releases.

Auslösebedingungen und Nebenläufigkeitskontrolle

ci.ymlDie Auslösekonfiguration von

📎 .github/workflows/ci.yml:2-11

on:
  push:
    branches:
      - '**'
    tags:
      - '!**'
  pull_request:
    branches:
      - main
      - minor

Hier gibt es zwei entscheidende Designs. Erstens:pushDas Ereignis überwacht alle Branches ('**'), schließt aber mittags: ['!**']explizit alle Tag-Pushes aus. Warum Tags ausschließen? Weil Tag-Pushes vonrelease.ymlseparat behandelt werden. Wennci.ymlebenfalls auf Tags reagieren würde, würden Release-Pipeline und CI-Pipeline doppelt ausgelöst, was Runner-Ressourcen verschwendet und sogar Race Conditions erzeugen kann. Zweitens:pull_requestüberwacht nurmainundminorzwei Branches – das ist Vues Zwei-Branch-Strategie:mainträgt die stabile Version,minorträgt die Vorabveröffentlichungsversion.

📎 .github/workflows/ci.yml:22-22

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

Der Ausdruck vongroupverwendetgithub.event.pull_request.number || github.refals Fallback: PR-Ereignisse verwenden die PR-Nummer als Gruppierungsschlüssel, Push-Ereignisse verwenden ref (Branch-Name) als Gruppierungsschlüssel. Das bedeutet, dass mehrere Pushes desselben PR in dieselbe Nebenläufigkeitsgruppe fallen. Undcancel-in-progressist nur bei PR-Ereignissentrue– wenn du drei Commits hintereinander pushst, werden die CI-Läufe der ersten beiden automatisch abgebrochen, und nur der neueste bleibt erhalten.

Der Einstieg in die dreifachen Gates: Bedingungsprüfung des test-Jobs

📎 .github/workflows/ci.yml:22-22

jobs:
  test:
    if: ${{ ! startsWith(github.event.head_commit.message, 'release:') && (github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository) }}
    uses: ./.github/workflows/test.yml

Bedingung enthält zwei logische Und-Zweige (if), und jeder verdient eine Erläuterung.&&Die erste Bedingung

: Wenn die Commit-Nachricht mit! startsWith(github.event.head_commit.message, 'release:')：如果提交信息以 release:Am Anfang, Tests überspringen. Genau das ist das Format der Commit-Nachricht, die release.js im vorherigen Kapitel gepusht hat – release.js hat die vollständigen Tests bereits lokal ausgeführt, CI muss nicht erneut validieren. Dies ist eine Optimierung des „Vertrauens in die vorgelagerte Instanz".

Beachten Sieuses: ./.github/workflows/test.yml– dies ist ein Aufruf eines reusable workflow.test.ymlist eine eigenständige Workflow-Datei, die vonci.ymlundrelease.ymlgemeinsam genutzt wird. Diese Wiederverwendung vermeidet die mehrfache Definition von lint/typecheck/test-Schritten in mehreren Workflows.

Kontinuierliche Vorabveröffentlichung: Die Rolle von pkg-pr-new

📎 .github/workflows/ci.yml:25-51

continuous-release:
  if: github.repository == 'vuejs/core'
  runs-on: ubuntu-latest
  steps:
    - name: Checkout
      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      with:
        persist-credentials: false
    # ... 安装 pnpm、Node.js、依赖 ...
    - name: Build
      run: pnpm build --withTypes
    - name: Release
      run: pnpx pkg-pr-new publish --compact --pnpm './packages/*' --packageManager=pnpm,npm,yarn

continuous-releaseDer Job läuft nur imvuejs/coreHaupt-Repository (if: github.repository == 'vuejs/core'), wird auf Forks nicht ausgeführt. Er erledigt drei Dinge: Build (pnpm build --withTypes, mit Typdeklarationen), dann mitpkg-pr-newalle Pakete unter./packages/*in eine temporäre npm-Registry veröffentlichen.

Beachten Sie, dass alle Actions auf Commit-SHA festgeschrieben sind (wieactions/checkout@3d3c42e5...), anstatt flüchtige Tags wie@v4zu verwenden. Dies ist eine harte Anforderung der Supply-Chain-Sicherheit – um zu verhindern, dass nach einer Kompromittierung des Action-Repositorys bösartiger Code automatisch eindringt.

ci.yml Kontrollflussdiagramm

flowchart TD
    trigger{"事件类型?"}
    trigger -->|"push 到任意分支"| push_check{"提交信息以 release: 开头?"}
    trigger -->|"PR 到 main/minor"| pr_check{"PR 来自 fork?"}

    push_check -->|"是"| skip_test["跳过 test job"]
    push_check -->|"否"| run_test["调用 test.yml"]

    pr_check -->|"是"| run_test
    pr_check -->|"否"| skip_test

    run_test --> test_result{"test.yml 通过?"}
    test_result -->|"否"| block["PR 被阻断"]
    test_result -->|"是"| cont_release{"仓库是 vuejs/core?"}

    cont_release -->|"是"| build["pnpm build --withTypes"]
    cont_release -->|"否"| end_node["结束"]
    build --> publish["pkg-pr-new publish"]
    publish --> end_node

---

Zwei, release.yml: Release-Orchestrierung nach Tag-Push

Intuitives Modell

Wenn manci.ymlals Sicherheitskontrolle bezeichnet,release.ymlist es die Startrampe. Wenn release.js lokal die Versionsnummer aktualisiert, committet, taggt und pusht, zündet das Tag-Push-Ereignis den Motor vonrelease.yml. Es führt zuerst einen vollständigen Testlauf aus (erneute Bestätigung), dann führt es im geschütztenReleaseEnvironmentpnpm release --publishOnlyaus und erstellt schließlich ein GitHub Release.

Ohne es wäre das von release.js gepushte Tag nur eine Git-Referenz, es gäbe keine neue Version auf npm und keine Release-Seite auf GitHub.

Auslösebedingung: Nur Tags werden akzeptiert

📎 .github/workflows/release.yml:3-6

on:
  push:
    tags:
      - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10

Es überwacht nur Tag-Pushes im Formatv*. Dies ergänzt sich mitci.ymlvontags: ['!**']– beide sind strikt gegenseitig ausschließend und werden nicht gleichzeitig ausgelöst.

Guard-Bedingungen des Release-Jobs

📎 .github/workflows/release.yml:8-21

jobs:
  test:
    uses: ./.github/workflows/test.yml

  release:
    if: github.repository == 'vuejs/core'
    needs: [test]
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    environment: Release

Hier gibt es drei Guard-Ebenen, keine davon ist verzichtbar.

Erste Ebeneif: github.repository == 'vuejs/core': Verhindert versehentliche Release-Auslösung auf Forks. Wenn jemand das Repository forkt und einv1.0.0-Tag pusht, verhindert diese Bedingung die Ausführung des Release-Prozesses.

Zweite Ebeneneeds: [test]: Der Release-Job hängt vom Test-Job ab. Der Test-Job rufttest.ymlauf; wenn die Tests fehlschlagen, startet der Release-Job gar nicht. Dies ist die harte Einschränkung „Tests müssen vor dem Release bestanden werden".

Bezüglich Berechtigungen:contents: writewird zum Erstellen des GitHub Release verwendet,id-token: writefür die npm-Provenance-Authentifizierung (OIDC-Token). Beachten Sie, dass hier keinpackages: writevorhanden ist, da Vue auf npm und nicht auf GitHub Packages veröffentlicht.

Die vollständige Kette der Release-Schritte

📎 .github/workflows/release.yml:37-46

- name: Install deps
  run: pnpm install --frozen-lockfile

- name: Update npm
  run: npm i -g npm@latest

- name: Build and publish
  id: publish
  run: |
    pnpm release --publishOnly

pnpm release --publishOnlyist der Einstiegspunkt von release.js aus dem vorherigen Kapitel.--publishOnlyDas Flag teilt release.js mit: Interaktive Versionsnummernauswahl überspringen, Git-Commit und Tagging überspringen (da das Tag bereits existiert), nur Build und npm publish ausführen.

GitHub Release erstellen

📎 .github/workflows/release.yml:48-57

- name: Create GitHub release
  id: release_tag
  uses: yyx990803/release-tag@8cccf7c5aa332d71d222df46677f70f77a8d2dc0 # v1.0.0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    tag_name: ${{ github.ref }}
    body: |
      For stable releases, please refer to [CHANGELOG.md](...) for details.
      For pre-releases, please refer to [CHANGELOG.md](...) of the `minor` branch.

release.yml Sequenzdiagramm

sequenceDiagram
    participant Dev as "开发者本地"
    participant GH as "GitHub"
    participant Test as "test.yml"
    participant Rel as "release job"
    participant NPM as "npm registry"

    Dev->>GH: "git push origin v3.x.x"
    GH->>Test: "触发 test.yml"
    Test-->>GH: "测试通过"
    GH->>Rel: "needs: [test] 满足"
    Rel->>Rel: "environment: Release 审批"
    Rel->>Rel: "pnpm install --frozen-lockfile"
    Rel->>Rel: "pnpm release --publishOnly"
    Rel->>NPM: "npm publish (OIDC provenance)"
    NPM-->>Rel: "发布成功"
    Rel->>GH: "release-tag 创建 Release"

---

Drei, size-report.yml und autofix.yml: Größenverfolgung und Format-Selbstheilung

size-report.yml: Workflow-übergreifender Größenregressionsbericht

size-report.ymlDie Auslösung ist sehr speziell – sie wird nicht direkt durch push oder PR ausgelöst, sondern durch das Abschlussereignis eines anderen Workflows.

📎 .github/workflows/size-report.yml:3-7

on:
  workflow_run:
    workflows: ['size data']
    types:
      - completed

workflow_runDas Event lauscht auf den Namensize datades Workflows, der abgeschlossen wurde. Dies ist ein zweistufiges Design:size-data.yml(In diesem Kapitel kein Quellcode bereitgestellt) ist dafür verantwortlich, im PR zu bauen und die Größe zu messen und die Ergebnisse als Artefakt hochzuladen;size-report.ymlnachsize dataAbschluss wird das Artefakt heruntergeladen, ein Bericht generiert und als Kommentar zum PR hinzugefügt.

📎 .github/workflows/size-report.yml:20-23

if: >
  github.repository == 'vuejs/core' &&
  github.event.workflow_run.event == 'pull_request' &&
  github.event.workflow_run.conclusion == 'success'

Dreifache Absicherung: Hauptrepository, PR-Event, Upstream-Workflow erfolgreich. Wennsize datafehlschlägt, wird der Report-Job nicht ausgeführt – weil keine Daten zum Berichten vorhanden sind.

Der Datenfluss gestaltet sich wie folgt:

📎 .github/workflows/size-report.yml:41-46

- name: Download Size Data
  uses: dawidd6/action-download-artifact@d63b86af1b34672e53c440b1b83979861906bad7 # v24
  with:
    name: size-data
    run_id: ${{ github.event.workflow_run.id }}
    path: temp/size

Vom Upstream-Workflow-Run wirdsize-datadas Artefakt nachtemp/sizeheruntergeladen. Dann werden parallel die PR-Nummer und der Base-Branch gelesen:

📎 .github/workflows/size-report.yml:48-59

- parallel:
    - name: Read PR Number
      id: pr-number
      uses: juliangruber/read-file-action@271ff311a4947af354c6abcd696a306553b9ec18 # v1.1.8
      with:
        path: temp/size/number.txt
    - name: Read base branch
      id: pr-base
      uses: juliangruber/read-file-action@271ff311a4947af354c6abcd696a306553b9ec18 # v1.1.8
      with:
        path: temp/size/base.txt

parallelist syntaktischer Zucker von GitHub Actions, der zwei unabhängige Schritte gleichzeitig ausführt.number.txtundbase.txtsindsize-data.ymlMetadatendateien, die beim Messen geschrieben werden.

Anschließend werden die historischen Größendaten des Base-Branches zum Vergleich heruntergeladen:

📎 .github/workflows/size-report.yml:61-69

- name: Download Previous Size Data
  uses: dawidd6/action-download-artifact@d63b86af1b34672e53c440b1b83979861906bad7 # v24
  with:
    branch: ${{ steps.pr-base.outputs.content }}
    workflow: size-data.yml
    event: push
    name: size-data
    path: temp/size-prev
    if_no_artifact_found: warn

Beachten Sieif_no_artifact_found: warn– wenn der Base-Branch noch keine historischen Daten hat (z. B. ein neuer Branch), schlägt es nicht fehl, sondern warnt nur. Dies stellt sicher, dass der Bericht beim ersten Lauf dennoch generiert wird, nur ohne Vergleichsbasis.

Schließlich wird der Bericht generiert und kommentiert:

📎 .github/workflows/size-report.yml:71-89

- name: Prepare report
  run: node scripts/size-report.js > size-report.md

- name: Read Size Report
  id: size-report
  uses: juliangruber/read-file-action@271ff311a4947af354c6abcd696a306553b9ec18 # v1.1.8
  with:
    path: ./size-report.md

- name: Create Comment
  uses: actions-cool/maintain-one-comment-backup@fbbc22ad1809c1bcf46f19b58397b6254773588c # backup for v3.0.0
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    number: ${{ steps.pr-number.outputs.content }}
    body: |
      ${{ steps.size-report.outputs.content }}
      <!-- VUE_CORE_SIZE -->
    body-include: '<!-- VUE_CORE_SIZE -->'

scripts/size-report.jsliesttemp/sizeundtemp/size-prevdie Daten unter und generiert einen Markdown-Bericht.maintain-one-comment-backupDie Action verwendetbody-include: '<!-- VUE_CORE_SIZE -->'als Marker, um sicherzustellen, dass pro PR nur ein Größenbericht-Kommentar erhalten bleibt (Aktualisierung statt Anhängen). Beachten Sie den Kommentar in L81, der erklärt, dass das ursprüngliche Action-Repository von GitHub blockiert wurde, daher wurde ein Backup-Repository verwendet und der Commit festgeschrieben.

autofix.yml: Automatische Behebung von Formatproblemen

autofix.ymllöst ein sehr praktisches Problem: Der von Mitwirkenden eingereichte Code entspricht nicht den prettier/eslint-Regeln, CI meldet einen Fehler, und die Mitwirkenden müssen manuellpnpm lint --fixausführen und erneut committen. Dieser Workflow automatisiert diesen Schritt.

📎 .github/workflows/autofix.yml:3-8

on:
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

Löst bei allen PRs aus, die Nebenläufigkeitssteuerung ist ähnlich wie beici.yml– ein neuer Push im selben PR bricht den alten autofix-Lauf ab.

📎 .github/workflows/autofix.yml:35-41

- name: Run eslint
  run: pnpm run lint --fix

- name: Run prettier
  run: pnpm run format

- uses: autofix-ci/action@7a166d7532b277f34e16238930461bf77f9d7ed8

Zuerst wird eslint--fixausgeführt, dann prettier formatiert, und schließlichautofix-ci/actionwerden die geänderten Dateien direkt zurück in den PR-Branch committet. Beachten Sie, dasspnpm run formatselbst ein Formatierungsbefehl ist (kein--fixFlag erforderlich, da das format-Skript internprettier --write）。

size-report Datenflussdiagramm

flowchart LR
    subgraph "size-data.yml (上游)"
        build_pr["构建 PR 分支"] --> measure["测量体积"]
        measure --> artifact_pr["artifact: size-data\n(number.txt, base.txt, 体积数据)"]
    end

    subgraph "size-report.yml (下游)"
        artifact_pr -->|"workflow_run 触发"| download["下载 size-data"]
        download --> read_meta["读取 number.txt / base.txt"]
        read_meta --> download_prev["下载 base 分支历史数据\n(if_no_artifact_found: warn)"]
        download_prev --> gen_report["node scripts/size-report.js"]
        gen_report --> comment["评论到 PR\n(标记: VUE_CORE_SIZE)"]
    end

---

Design-Überlegung: Normen in die Pipeline gießen

Bei der Betrachtung dieser vier Workflows lassen sich mehrere durchgängige Designprinzipien erkennen.

Erstens, Minimierung der Berechtigungen. ci.ymlundautofix.ymldeklarieren beidepermissions: contents: read, nurrelease.ymlbenötigtcontents: writeundid-token: write。size-report.ymlbenötigtpull-requests: writeundissues: writezum Kommentieren. Jeder Workflow erhält nur die Berechtigungen, die er wirklich benötigt.

Zweitens, Supply-Chain-Sicherheit.Alle Drittanbieter-Actions sind auf Commit-SHA festgeschrieben, nicht auf floatende Tags.size-report.ymlDer Kommentar in L81 erklärt sogar direkt, dass nach der Blockierung des ursprünglichen Action-Repositories auf ein Backup-Repository umgestellt und der Commit festgeschrieben wurde – dies ist eine praktische Verteidigung gegen Supply-Chain-Angriffe.

Drittens, Trennung der Zuständigkeiten und Wiederverwendung. test.ymlwird vonci.ymlundrelease.ymlgemeinsam genutzt, um Duplizierung der Testlogik zu vermeiden.size-data.ymlundsize-report.ymlsind getrennt, sodass Messung und Berichterstattung unabhängig voneinander weiterentwickelt werden können.

Viertens, die Wahl der Fehlerrichtung. size-report.ymlDieif_no_artifact_found: warnwählt „Warnen statt Fehlschlagen“, da fehlende historische Daten den PR nicht blockieren sollten. Dierelease.ymlvonneeds: [test]wählt „Testfehler blockiert Release“, da ein Release eine irreversible Operation ist.

Fünftens, Differenzierung der Nebenläufigkeitssteuerung.PR-Events brechen alte Läufe ab (cancel-in-progress: true), push-Events brechen nicht ab (cancel-in-progress: false). Diese Differenz spiegelt die Semantik der beiden Events wider: Alte Commits eines PRs sind bedeutungslos, jeder Commit eines push kann der endgültige Zustand sein.

---

Zusammenfassung dieses Kapitels

Dieses Kapitel analysiert die vier Kern-Workflows des Vue-core-Repositories:

• ci.yml: PR-Gate + kontinuierliche Vorabveröffentlichung. DurchifBedingungen werden push/PR und fork/gleiches Repository unterschieden, mitconcurrencywerden veraltete PR-Läufe abgebrochen, mitpkg-pr-newwerden installierbare Vorabveröffentlichungspakete veröffentlicht.
• release.yml: Tag-ausgelöste offizielle Veröffentlichung. Drei Schutzebenen (Repository-Prüfung, needs test, environment-Genehmigung) stellen sicher, dass nur Tags, die Tests bestanden haben und genehmigt wurden, in npm veröffentlicht werden können.
• size-report.yml: Workflow-übergreifender Größenregressionsbericht. Durchworkflow_run-Event wird das Upstream-size data-Event überwacht, das Artifact heruntergeladen und mit den Daten des Base-Branches verglichen, um als Kommentar zum PR zurückgemeldet zu werden.
• autofix.yml: Automatische Formatkorrektur. Auf dem PR werden eslint --fix und prettier ausgeführt, und durchautofix-ci/actionwerden die Korrekturen direkt in den PR-Branch zurückcommittet.

Diese vier Workflows bilden gemeinsam eine „nicht umgehbare Pipeline": Code-Standards werden durch autofix automatisch korrigiert, Typen und Tests werden durch ci.yml erzwungen geprüft, Größenregressionen werden durch size-report verfolgt, und die Veröffentlichung wird durch release.yml unter mehrfachen Schutzebenen ausgeführt.

Gedanken und Selbsttest dieses Kapitels

---

geändert würde, würden neue Branches oder PRs beim ersten Lauf fehlschlagen, weil keine Base-Daten gefunden werden – was offensichtlich unvernünftig ist.scripts/size-report.jswählt „bei Testfehler die Veröffentlichung blockieren", weil die Veröffentlichung eine irreversible Operation ist und die Codequalität sichergestellt werden muss. Wenn vertauscht – size-report schlägt bei fehlenden Daten fehl, release veröffentlicht trotz Testfehler – würde Ersteres zu zahlreichen Fehlalarmen führen, die normale PRs blockieren, und Letzteres würde ungetesteten Code in npm gelangen lassen. Dies spiegelt das Designprinzip der Fehlerrichtung wider: „locker bei unterstützenden Informationen, streng bei irreversiblen Operationen".usage-sizeDas nächste Kapitel wird sich mit dem Kern des Größenbudget-Mechanismus befassen:

wie Größendaten geparst werden, wie Inkremente berechnet werden, wie die Ausgabe formatiert wird, und die Messphilosophie vonscripts/size-report.js– warum Vue sich dafür entscheidet, die „tatsächlich genutzte Größe" statt der „vollständigen Paketgröße" zu messen.scripts/usage-size.jsVom PR-Gate bis zur Tag-Veröffentlichung bilden vier Workflow-Dateien gemeinsam eine nicht umgehbare automatisierte Wächterkette. Aber die Pipeline kann Merges nur blockieren, wenn sie quantifizierbare Beurteilungsgrundlagen besitzt. Das nächste Kapitel wird sich auf Vues engineeringmäßige Governance der Paketgröße als Kernmetrik konzentrieren:

Im vorherigen Kapitel haben wir gesehen, wie Vue mit GitHub Actions Linting, Typprüfung, Tests und Größenverfolgung in eine nicht umgehbare Pipeline integriert, wobei size-report.yml und size-data.yml dafür verantwortlich sind, nach jeder Änderung Größen-Daten zu hinterlassen. Aber die Pipeline führt nur aus; was tatsächlich beantwortet, „um wie viel größer und wo größer", sind die beiden Skripte, die in diesem Kapitel analysiert werden. Der Kernkonflikt des Größenbudgets liegt darin: Die Paketgröße ist eine Metrik, die nur wahrgenommen, aber schwer präzise zugeordnet werden kann. Wenn Benutzer sich beschweren, dass „Vue zu groß ist", müssen die Maintainer drei Fragen beantworten – um wie viel größer? Wo größer? Hat diese Änderung es noch größer gemacht? scripts/size-report.js ist für den Vergleich zuständig, scripts/usage-size.js für die Zuordnung; beide bilden gemeinsam die Messphilosophie des Größenbudgets.

11.1 size-report: Größenunterschiede in eine lesbare Markdown-Tabelle verwandeln

Intuitives Modell

Stellen Sie sich vor, Sie sind Qualitätsprüfer bei einem Logistikunternehmen. Jedes Paket (Build-Artefakt) muss vor dem Versand gewogen werden, und Ihre Aufgabe ist nicht das Wiegen selbst, sondern „das heutige Gewicht" und „das gestrige Gewicht" nebeneinander in eine Tabelle zu setzen und mit fettgedrucktem+2.3 kBzu markieren, welche Pakete schwerer geworden sind. Ohne diese Vergleichstabelle sehen Maintainer nur eine Ansammlung isolierter Zahlen und können nicht beurteilen, ob ein PR eine Größenregression eingeführt hat.

size-report.jsist genau dieser Qualitätsprüfer. Es erzeugt keine Größen-Daten (das ist Aufgabe vonusage-size.jsund den Build-Skripten), es konsumiert nur JSON-Dateien aus zwei Verzeichnissen und generiert einen Markdown-Bericht.

Datenstruktur und Verzeichniskonventionen

Die Kernkonventionen des Skripts verbergen sich in zwei Konstanten. Das aktuelle Datenverzeichnis isttemp/size, das historische Basisverzeichnis isttemp/size-prev。

📎 scripts/size-report.js:23-24

Die Benennung dieser beiden Verzeichnisse ist nicht willkürlich:temp/sizewird vomsize-data.yml-Workflow bei jedem Lauf generiert und als Artefakt hochgeladen📎 .github/workflows/size-data.yml:53-57, währendtemp/size-prevvonsize-report.ymlnach dem Herunterladen des Basis-Artefakts entpackt wird. Der Verzeichnisname selbst ist der Vertrag des Datenflusses.

Das Skript definiert drei Typ-Aliase, die die Struktur der JSON-Dateien präzise beschreiben:

📎 scripts/size-report.js:8-21

SizeResulthat drei numerische Felder:size(unkomprimiert),gzip、brotli。BundleResultfügt darauf basierend dasfile-Feld hinzu, um den Dateinamen anzuzeigen.UsageResultist einRecord, der Schlüssel ist der Preset-Name, der Wert istSizeResult & { name: string }– beachten Sie, dass hier ein zusätzlichesname-Feld vorhanden ist, da die Schlüssel des JSON-Objekts nachObject.valuesverloren gehen und der Name redundant im Wert gespeichert werden muss.

Step-by-Step Walkthrough

Der Hauptablauf ist minimalistisch, nur zwei Schritte plus eine Ausgabe:

📎 scripts/size-report.js:23-38

run()Zuerst wirdrenderFiles()aufgerufen, um die Tabelle der Artefaktdateien zu rendern, dannrenderUsages(), um die Tabelle der Nutzungsszenarien zu rendern, und schließlich wird der in der Modulvariablenoutputakkumulierte String auf einmal nach stdout geschrieben📎 scripts/size-report.js:25. Dieses Muster „Strings akkumulieren und auf einmal ausgeben" vermeidet den Konkatenierungsaufwand mehrfacherprocess.stdout.writeund macht die Ausgabereihenfolge vollständig kontrollierbar.

Erster Schritt: Dateiliste sammeln und Vereinigung bilden.

📎 scripts/size-report.js:44-49

filterFilesfiltert zwei Arten von Dateien heraus: solche, die mit_beginnen (wie_usages.json), und solche, die mit.txtenden (wienumber.txt、base.txt). Diese beiden Dateitypen sind Metadaten, keine Größen-Daten. Dann wird die VereinigungfileListder Dateinamen des aktuellen und des historischen Verzeichnisses gebildet – mitSetzur Deduplizierung. Warum die Vereinigung? Weil eine Datei nur im historischen Verzeichnis existieren kann (dieser Build hat das Artefakt gelöscht) oder nur im aktuellen Verzeichnis (dieser Build hat ein Artefakt hinzugefügt). Beide Fälle müssen im Bericht erscheinen.

Zweiter Schritt: Dateiweiser Vergleich.

📎 scripts/size-report.js:43-75

Für jede Datei in der Vereinigung wird versucht, JSON aus beiden Verzeichnissen zu importieren.importJSONDie Implementierung ist „gibt undefined zurück, wenn die Datei nicht existiert":

📎 scripts/size-report.js:112-115

Hier wird dynamischesimport()in Kombination mitwith: { type: 'json' }Import-Assertions verwendet, nichtfs.readFileSync + JSON.parse. Ersteres wird vom Modul-Loader von Node verarbeitet, letzteres erfordert manuelle Behandlung von Kodierungs- und Parsing-Fehlern. Der Preis für die Wahl vonimport()ist, dass es ein Promise zurückgibt, daher ist das gesamterenderFilesasync.

Der entscheidende Zweig liegt inif (!curr): Wenn das aktuelle Verzeichnis diese Datei nicht enthält, bedeutet das, dass das Artefakt gelöscht wurde; dann wird die Markdown-Durchstreichungs-Syntax~~fileName~~verwendet, um📎 scripts/size-report.js:60-61zu markieren. Andernfalls wird normal eine Zeile gerendert, wobei an jeden numerischen Wert das Ergebnis vongetDiffangehängt wird.

Dritter Schritt: Differenz berechnen.

📎 scripts/size-report.js:124-130

getDiffhat drei vorzeitige Rückkehrpunkte:prev === undefinedgibt einen leeren String zurück (keine Basislinie, kein Vergleich möglich);diff === 0gibt einen leeren String zurück (keine Änderung, kein Rauschen anzeigen); andernfalls wird die fettgedruckte vorzeichenbehaftete Differenz zurückgegeben. Beachten Sie, dassprettyBytes(diff)auch negative Zahlen korrekt behandelt und-1.2 kBausgibt, während die Variablesignnur bei positiven Zahlen ein+。

ergänzt.

📎 scripts/size-report.js:80-103

renderUsagesVierter Schritt: usage-Tabelle rendern.renderFilesDer strukturelle Unterschied zu_usages.jsonist beachtenswert: Es importiert direktObject.values(curr), da die usage-Daten fest in dieser einen Datei liegen.prev?.[usage.name]wandelt das Record in ein Array um und sucht dann übernamedie historischen Daten anhand des Namens – genau deshalb wird das.filter(usage => !!usage)-Feld redundant gespeichert.mapDiese Zeile ist tatsächlich redundant, da

immer ein Array-Element zurückgibt und keinen falsy-Wert erzeugen kann.markdown-tableSchließlich wird die Bibliothek📎 scripts/size-report.js:72-74。

flowchart TD
    start["run()"] --> rf["renderFiles()"]
    rf --> read_curr["readdir(temp/size)"]
    rf --> read_prev{"existsSync(temp/size-prev)?"}
    read_prev -->|是| read_prev_dir["readdir(temp/size-prev)"]
    read_prev -->|否| empty_prev["prev = []"]
    read_curr --> union["fileList = Set(curr ∪ prev)"]
    read_prev_dir --> union
    empty_prev --> union
    union --> loop{"遍历 fileList"}
    loop -->|每个 file| import_c["importJSON(currPath)"]
    loop -->|每个 file| import_p["importJSON(prevPath)"]
    import_c --> check_curr{"curr 存在?"}
    check_curr -->|否| deleted["push(~~fileName~~)"]
    check_curr -->|是| render_row["push(fileName, size+diff, gzip+diff, brotli+diff)"]
    deleted --> loop
    render_row --> loop
    loop -->|遍历结束| ru["renderUsages()"]
    ru --> import_u["importJSON(_usages.json)"]
    import_u --> table["markdownTable 渲染"]
    table --> out["process.stdout.write(output)"]

Kopieren

filterFilesImport-Assertions für JSON sind die Standardpraxis ab Node 20+ und behandeln nativ das Laden von JSON in ESM-Umgebungen. Der Preis ist, dass sie nicht im synchronen Kontext verwendet werden können und jeder Import vom Modul-Cache erfasst wird – aber in diesem Einmal-Skript ist Caching kein Problem.file[0] !== '_'Die-Prüfung vonreaddirDiese Prüfung geht davon aus, dass der Dateiname nicht leer ist. Wennfile[0]einen leeren String zurückgibt (theoretisch unmöglich), istundefined，undefined !== '_'gleich

Behandlung gelöschter Artefakte.Wenn ein Artefakt gelöscht wird, markiert der Bericht es mit Durchstreichung, anstatt es direkt zu entfernen. Das ist beabsichtigtes Design: Maintainer müssen sehen können, „diese Datei ist verschwunden", statt dass sie stillschweigend aus der Tabelle verschwindet. Würde man sie einfach herausfiltern, könnten Leser fälschlich annehmen, das Artefakt habe nie existiert.

11.2 usage-size: Simulation des Import-Szenarios eines echten Nutzers

Intuitives Modell

size-reportsagt dir „wie groß das vollständige Paket ist", aber das beantwortet nicht die Frage, die Nutzer wirklich interessiert: „Wenn ich nurcreateAppverwende, wie viel Code muss ich tatsächlich herunterladen?" Die Größe des vollständigen Pakets enthält viel Code, den du wahrscheinlich nie brauchst (z. B.defineCustomElement、Transition、KeepAlive）。usage-size.jsbesteht darin, einen „typischen Nutzer" zu spielen: eine virtuelle Einstiegsdatei schreiben, die nur bestimmte APIs importiert, mit Rollup bündeln und sehen, wie groß das endgültige Artefakt ist.

Das ist so, als würde ein Restaurant dir nicht sagen „alle Zutaten in der Küche wiegen insgesamt 50 Kilogramm", sondern „wenn du eine Portion Kung Pao Huhn bestellst, sind die tatsächlich verwendeten Zutaten 300 Gramm".

Datenstruktur: Preset-Array

Die zentrale Datenstruktur des Skripts istpresetsArray, wobei jedes Element ein Nutzungsszenario beschreibt:

📎 scripts/usage-size.js:27-55

PresetDer Typ hat drei Felder:name(Anzeigename),imports(Liste der aus Vue importierten APIs), optionalreplace(zusätzliche Compile-Zeit-Ersetzungen). Fünf Presets decken Nutzungsszenarien vom kleinsten bis zum größten ab:

• createApp (CAPI only): nur importierencreateApp, und__VUE_OPTIONS_API__ersetzen durch'false', Simulation eines reinen Composition-API-Nutzers📎 scripts/usage-size.js:35-40
• createApp: nur importierencreateApp, Options API beibehalten📎 scripts/usage-size.js:35-40
• createSSRApp: SSR-Szenario📎 scripts/usage-size.js:35-40
• defineCustomElement: Web-Components-Szenario📎 scripts/usage-size.js:35-40
• overall: sechs Kern-APIs importieren, Simulation eines „voll ausgestatteten" Nutzers📎 scripts/usage-size.js:44-54

Die Einstiegsdatei ist fest auf das runtime-only esm-bundler-Artefakt gesetzt:

📎 scripts/usage-size.js:24-28

Auswahlvue.runtime.esm-bundler.jsstatt der vollständigen Versionvue.esm-bundler.js, weil die Runtime-Version keinen Template-Compiler enthält und damit näher an der tatsächlichen Situation moderner Build-Tool-Nutzer liegt – sie verwenden SFCs zum Vorkompilieren von Templates und benötigen keinen Runtime-Compiler.

Step-by-Step Walkthrough

Erster Schritt: Alle Preset-Bundles parallel erzeugen.

📎 scripts/usage-size.js:62-69

main()Für jedes PresetgenerateBundlePromise erstellen, mitPromise.allparallel ausführen. Parallelität ist hier sicher, weil jedergenerateBundleAufruf unabhängig istrollup(), keinen gemeinsamen Zustand teilt.

Zweiter Schritt: Virtuellen Einstieg konstruieren.

📎 scripts/usage-size.js:94-96

Dies ist der raffinierteste Teil des gesamten Skripts. Es schreibt keine temporäre Datei auf die Festplatte, sondern konstruiert eine virtuelle Modul-IDvirtual:entry, deren Inhalt eine re-export-Anweisung ist:export { createApp } from '/absolute/path/to/vue.runtime.esm-bundler.js'. Beachteentryist ein absoluter Pfad, weil Rollup ihn auflösen können muss.

Dritter Schritt: Rollup-Plugin-Kette konfigurieren.

📎 scripts/usage-size.js:98-121

Die Reihenfolge des Plugin-Arrays ist entscheidend:

1. Benutzerdefiniertusage-size-plugin：resolveIdabfangenvirtual:entrygibt sich selbst zurück,loadgibt virtuellen Inhalt zurück📎 scripts/usage-size.js:101-110. Dies ist das Standardmuster für virtuelle Module in Rollup.

2. nodeResolve(): auflösenvue.runtime.esm-bundler.jsinterne import📎 scripts/usage-size.js:111。

3. replace: Compile-Zeit-Konstanten injizieren📎 scripts/usage-size.js:112-119。

replaceDie Plugin-Konfiguration offenbart den Kernmechanismus des esm-bundler-Artefakts: Es behält__VUE_OPTIONS_API__、__VUE_PROD_DEVTOOLS__und andere Runtime-Flags bei, die vom Build-Tool des Nutzers ersetzt werden. Hier übernimmt das Skript die Ersetzung für den Nutzer:

• process.env.NODE_ENV → "production": Produktionszweig verwenden
• __VUE_PROD_DEVTOOLS__ → 'false': devtools-Unterstützung deaktivieren
• __VUE_PROD_HYDRATION_MISMATCH_DETAILS__ → 'false': ausführliche Hydration-Fehlermeldungen deaktivieren
• __VUE_OPTIONS_API__ → 'true': Options API standardmäßig beibehalten

Dann...preset.replaceerweitern, damit Presets die Standardwerte überschreiben können.createApp (CAPI only)Das Preset nutzt genau diesen Mechanismus, um__VUE_OPTIONS_API__zu ändern in'false' 📎 scripts/usage-size.js:35-40。

preventAssignment: trueErsetzung verhindernobj.process.env.NODE_ENV = xsolcher Zuweisungsanweisungen📎 scripts/usage-size.js:117。

Vierter Schritt: Generieren, Komprimieren, Messen.

📎 scripts/usage-size.js:123-134

result.generate({})Code erzeugen,output[0].codeabrufen. Dann mit SWC komprimieren:

📎 scripts/usage-size.js:125-130

module: truebedeutet, die Eingabe ist ESM,toplevel: trueerlaubt das Komprimieren von Variablennamen im Top-Level-Scope. Nach der Komprimierung werden drei Metriken berechnet:minified.length(Byte-Länge),gzipSync(minified).length、brotliCompressSync(minified).length。

Beachte, dass hiernode:zlibsynchrone API verwendet wird, nicht die asynchrone Version. In einem Einmal-Skript ist die synchrone API prägnanter, und die Komprimierung selbst ist eine CPU-intensive Operation, sodass Asynchronität keinen Parallelitätsgewinn bringt.

Fünfter Schritt: Ausgabe und Persistenz.

📎 scripts/usage-size.js:62-86

Die Ergebnisse werden zunächst in menschenlesbarem Format auf der Konsole ausgegeben, mitpicoeingefärbt📎 scripts/usage-size.js:62-86. Dann intemp/size/_usages.jsonschreiben, mitObject.fromEntriesdas Array zurück in ein Record umwandeln, Schlüssel ist der Preset-Name📎 scripts/usage-size.js:81-85。

--writeDas Flag steuert, ob zusätzlich das unkomprimierte Bundle jedes Presets auf die Festplatte geschrieben wird📎 scripts/usage-size.js:136-138, zum Debuggen.

flowchart LR
    subgraph preset_loop["presets 并行遍历"]
        p1["Preset: createApp"]
        p2["Preset: overall"]
    end
    p1 --> virtual["virtual:entry\n'export { createApp } from ...'"]
    p2 --> virtual
    virtual --> rollup["rollup({ input: virtual:entry })"]
    rollup --> resolve["nodeResolve()\n解析 vue.runtime.esm-bundler.js"]
    resolve --> replace["replace()\n__VUE_OPTIONS_API__ 等"]
    replace --> gen["result.generate()\noutput[0].code"]
    gen --> minify["swc.minify(module, toplevel)"]
    minify --> metrics["size / gzipSync / brotliCompressSync"]
    metrics --> json["_usages.json"]

Designüberlegungen und Stolperfallen

replaceDiepreventAssignmentFalle.WennpreventAssignment: true，replacenicht gesetzt wird, ersetzt das Plugin auchprocess.env.NODE_ENV = 'x'solche Zuweisungsanweisungen und erzeugt"production" = 'x'Syntaxfehler. Im Vue-Quellcode existieren tatsächlich Zuweisungen anprocess.env.NODE_ENV(in Testwerkzeugen), daher ist diese Option erforderlich.

__VUE_OPTIONS_API__Wahl des Standardwerts.Das Skript setzt den Standardwert auf'true' 📎 scripts/usage-size.js:116, nicht auf'false'. Dies ist eine konservative Wahl: Wenn der Nutzer nichts konfiguriert, behält Vue die Options-API-Unterstützung bei.createApp (CAPI only)Das Preset überschreibt explizit auf'false', um den Größenvorteil nach dem Deaktivieren zu zeigen. Dieser Vergleich ist selbst Dokumentation für den Nutzer: Er zeigt, „wie viel man spart, wenn man die Options API abschaltet".

ParallelPromise.allFehlersemantik.Wenn das Bündeln eines Presets fehlschlägt,Promise.allwird sofort abgelehnt, andere laufende Bundling-Vorgänge werden nicht abgebrochen (Rollup bietet keinen Abbruchmechanismus). In CI bedeutet dies, dass ein Fehler die Berechnung anderer Presets verschwendet, aber das Skript selbst mit einem Nicht-Null-Exit-Code endet, den CI korrekt erfassen kann.

11.3 Von Daten zur Zugangskontrolle: Wie CI diese Berichte konsumiert

Datenfluss-Panorama

Um diese beiden Skripte zu verstehen, muss man sie in die CI-Pipeline einordnen.size-data.ymlläuft bei Push auf main/minor oder bei PRpnpm run size 📎 .github/workflows/size-data.yml:45, erzeugttemp/sizeVerzeichnis, lädt es dann als Artifact hoch📎 .github/workflows/size-data.yml:53-57。

Für PRs schreibt es zusätzlich zwei Metadatendateien:

📎 .github/workflows/size-data.yml:47-51

number.txtspeichert die PR-Nummer,base.txtspeichert den Namen des Zielbranches. Diese beiden Dateien sind genau diesize-report.jsinfilterFilesherauszufilternden.txtDateien📎 scripts/size-report.js:44-45. Sie existieren, damit der nachgelagertesize-report.ymlweiß, „mit welcher Baseline verglichen werden soll".

Abruf und Vergleich der Baseline

size-report.yml(im vorherigen Kapitel ausführlich beschrieben) ist: dassize-dataArtifact des aktuellen PR herunterladen, das Baseline-Artifact des Zielbranches herunterladen, die Baseline nachtemp/size-preventpacken und dannsize-report.jsausführen, um einen Markdown-Bericht zu erzeugen und als Kommentar zum PR hinzuzufügen.

Hier gibt es eine entscheidende Design-Einschränkung:size-report.jsselbst ist nicht für den Abruf der Baseline verantwortlich, es setzt voraus, dasstemp/size-prevbereits existiert. Falls nicht,existsSync(prevDir)gibt false zurück,previst ein leeres Array📎 scripts/size-report.js:48, alle Diffs sind leere Strings. Dies ist eine elegante Degradierung: Ohne Baseline wird der Bericht trotzdem erzeugt, nur ohne Unterschiede anzuzeigen.

Die Entscheidungslogik der Größen-Zugangskontrolle

Dieses Design der „Trennung von Messung und Entscheidung" hat einen tiefen Grund: Das Messskript sollte rein bleiben und nur Fakten produzieren; die Entscheidungslogik sollte auf Workflow-Ebene liegen, da Schwellenwerte je nach Version, Branch und Release-Phase variieren können. Schwellenwerte fest insize-report.jszu kodieren würde seine Wiederverwendbarkeit erschweren.

Design-Überlegungen

Warum braucht das Größenbudget zwei Messgrößen?Die vollständige Paketgröße und die Usage-Größe beantworten unterschiedliche Fragen. Die vollständige Paketgröße ist die „Obergrenze" – sie sagt, wie viel der Nutzer im schlimmsten Fall herunterladen muss. Die Usage-Größe ist der „typische Wert" – sie sagt, wie viel die meisten Nutzer tatsächlich herunterladen. Erst beide zusammen ergeben ein vollständiges Größenbild. Gäbe es nur die vollständige Paketgröße, würden Maintainer dazu neigen, seltene APIs übermäßig zu optimieren; gäbe es nur die Usage-Größe, könnten Größencxplosionen in bestimmten Randfällen übersehen werden.

Die Bedeutung der Doppelmetrik gzip und brotli.Moderne CDNs unterstützen brotli weitgehend, aber nicht in allen Szenarien ist es aktiviert. Beide gleichzeitig zu berichten ermöglicht Maintainern einzuschätzen, „wie die Größe in Umgebungen aussieht, die nur gzip unterstützen". brotli ist typischerweise 15-20% kleiner als gzip, und dieser Unterschied selbst ist wertvolle Information.

Der Stabilitätsvertrag des Datenformats. size-report.jsundusage-size.jssind über JSON-Dateien entkoppelt.usage-size.jsschreibt_usages.json，size-report.jsliest es. Die Feldnamen dieses Vertrags (name、size、gzip、brotli) sind implizit, es gibt keine Schema-Validierung. Wennusage-size.jsFeldnamen ändert und vergisst,size-report.jszu synchronisieren, zeigt der Bericht stillschweigend falsche Daten an. Dies ist die Schwachstelle des aktuellen Designs.

Zusammenfassung dieses Kapitels

Überlegungen und Selbsttests zu diesem Kapitel

---

Der Größenbudget-Mechanismus löst die Fragen „was messen“ und „wie vergleichen“, aber er setzt eine Prämisse voraus: Das Build-Artefakt selbst ist reproduzierbar. Das nächste Kapitel führt in die minimale Debug-Sandbox ein:vite-debugWie man mit minimaler Konfiguration eine interaktive Vue-Entwicklungsumgebung startet und wie sie mit lokalen Build-Artefakten interagiert, um einen geschlossenen Kreislauf von Quellcode-Änderungen bis zur Laufzeitvalidierung zu bilden.

Damit ist der Messkreislauf des Größenbudgets klar: size-report.js beantwortet mit dem Verzeichnisvergleich „um wie viel größer“, usage-size.js simuliert mit virtuellen Modulen reale Importszenarien und beantwortet „wo größer“, während die Gate-Entscheidung der Workflow-Ebene überlassen bleibt. Dieser Mechanismus verwandelt Größenregressionen von vagen Beschwerden in nachverfolgbare Daten. Aber Daten können nur sagen, dass ein Problem existiert; um es wirklich zu lokalisieren und zu beheben, braucht man eine minimale Umgebung, die das Problem schnell reproduziert. Das nächste Kapitel führt in packages-private/vite-debug ein und zeigt, wie Vue mit Vite + SFC eine minimalistische Debug-Sandbox aufbaut und „minimale Reproduktion auf echtem Quellcode“ zu einer praktikablen Alltagspraxis macht.

Im vorherigen Kapitel haben wir den Messkreislauf des Größenbudgets abgeschlossen: size-report.js beantwortet „um wie viel größer“, usage-size.js beantwortet „wo größer“, und die Workflow-Ebene ist für die Gate-Entscheidung verantwortlich. Dieser Mechanismus hat jedoch eine implizite Voraussetzung – das Build-Artefakt selbst ist reproduzierbar. Wenn man feststellt, dass ein Paket ungewöhnlich stark an Größe zunimmt oder ein Laufzeitverhalten nicht den Erwartungen entspricht, braucht man eine minimale Umgebung, die lokalen Quellcode schnell lädt und Änderungen sofort sichtbar macht. packages-private/vite-debug ist diese Umgebung. Sie hat nur vier Dateien und insgesamt weniger als 40 Zeilen Code, bildet aber den Einstieg in die Alltagspraxis „minimale Reproduktion auf echtem Quellcode“ im Vue-core-Repository. Dieses Kapitel zerlegt die Konstruktionslogik dieser Sandbox Datei für Datei und erklärt, warum sie unter packages-private und nicht unter packages liegt.

I. Das Skelett der Sandbox:main.tsundApp.vueminimale Mount-Kette

Intuitives Modell

Wenn man die gesamte Vue-Laufzeit mit einem Motor vergleicht, dann istvite-debugein „nackter Prüfstand“ – ohne Gehäuse, ohne Armaturenbrett, nur mit der minimalen Verkabelung, damit der Motor läuft. Sein Wert liegt nicht in funktionaler Vollständigkeit, sondern darin,alle störenden Variablen auszuschließen: Wenn man vermutet, dass ein Bug im Reaktivitätssystem oder im Renderer liegt, möchte man nicht, dass die Komplexität der Debug-Umgebung selbst zur Rauschquelle wird.

Datenstruktur und Dateilayout

Zuerst der gesamte Inhalt vonmain.ts:

📎 packages-private/vite-debug/main.ts:4-4

import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.mount('#app')

Diese sechs Zeilen Code sind das Standardparadigma zum Starten einer Vue-Anwendung, aber jede Zeile hat im Debug-Szenario eine präzise technische Bedeutung:

• L1Inimport { createApp } from 'vue'von'vue'hängt davon ab, wohin der Modulbezeichnervite.config.tsletztlich aufgelöst wird, vollständig von den Abhängigkeitsdeklarationen inpackage.jsonund
• L2ab. Dies ist der entscheidende Punkt der gesamten Sandbox – wir werden später sehen, wie er auf lokalen Quellcode zeigt.import App from './App.vue'Das@vitejs/plugin-vuevonApp.vuelöst die SFC-Kompilierungspipeline von<script>、<template>、<style>aus: Vite registriert dieses Plugin beim Start des Dev-Servers; wenn der Browser
• L4anfordert, zerlegt das Plugin es increateApp(App)drei virtuelle Module, die separat kompiliert werden.app._context、app._instanceDas
• L6vonapp.mount('#app')erstellt die Anwendungsinstanz; zu diesem Zeitpunkt initialisiert Vue internappund andere Kernfelder, löst aber noch kein Rendering aus.

Dasindex.htmlvonindex.htmlist der eigentliche Startschalter: Es sucht im DOM das Containerelement mit der ID<div id="app"></div>, erstellt die Root-Komponenteninstanz und löst das erste Rendering aus.<script type="module" src="/main.ts"></script>Beachten Sie, dass hier kein Verweis aufapp.mount('#app')vorhanden ist – Vites Konvention ist, dass

im Projektstammverzeichnis als Einstiegs-HTML dient, das

undApp.vueenthält. Obwohl diese Datei nicht in den keyFiles dieses Kapitels steht, ist sie die Voraussetzung dafür, dass

📎 packages-private/vite-debug/App.vue:4-8

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <button @click="count++">{{ count }}</button>
</template>

<style>
button {
  color: red;
}
</style>

Szenariogesteuerter Walkthrough: Die vollständige Kette eines KlicksNun betrachten wir

, den „Versuchsträger“ dieser Sandbox:

@vitejs/plugin-vueKopierenApp.vueIn ein konkretes Szenario übertragen:

• <script setup>Was passiert, wenn der Benutzer im Browser auf die Schaltfläche klickt?setup()Erster Schritt: SFC-Kompilierungsphase (beim Start des Dev-Servers)ref(0)kompiliertRefImplin drei Teile:.valueDer0。
• <template>-Block wird in die{{ count }}-Funktion der Komponente kompiliert,_toDisplayString(count.value)，@click="count++"der Aufruf gibt einonClick: $event => (count.value++)。
• <style>-Objekt zurück, dessen<style>anfangs

ist. Derapp.mount-Block wird in eine Renderfunktion kompiliert,

createApp(App)wird umgewandelt inmount('#app')wird die Root-Komponente erstelltComponentInternalInstance, ausgeführtsetup()ergibtcountdie RefImpl, und dann wird die Render-Funktion aufgerufen, um den VNode-Baum zu erzeugen. In der Render-Funktion wirdcount.valuegelesen, wastrackauslöst, Abhängigkeiten zu sammeln – der aktuell aktive Render-Effekt (ReactiveEffect) wird incountindepaufgezeichnet.

Dritter Schritt: Klick-Ereignis (bei Benutzerinteraktion)

Der Browser löst dasclick-Ereignis aus, und der Event-Handler von Vue führtcount.value++aus. Dies ist eine Setter-Operation, dietriggerauslöst: Durchlaufen der incount.depgesammelten Effekte und Planen des erneuten Renderns. Da es sich um eine synchrone Aktualisierung handelt und sie sich nicht in der Batch-Warteschlange befindet, wird der Render-Effekt sofort ausgeführt, die Render-Funktion erneut aufgerufen, ein neuer VNode erzeugt, ein Diff mit dem alten VNode durchgeführt, festgestellt, dass sich der Textinhalt von0zu1geändert hat, und das echte DOM aktualisierttextContent。

Die gesamte Kette kann mit dem folgenden Datenflussdiagramm dargestellt werden:

flowchart LR
    subgraph compile["编译期 (Vite Dev Server)"]
        sfc["App.vue"] -->|"@vitejs/plugin-vue"| script["setup() 函数"]
        sfc -->|"@vitejs/plugin-vue"| render["渲染函数"]
        sfc -->|"@vitejs/plugin-vue"| style["CSS 模块"]
    end
    subgraph runtime["运行时 (浏览器)"]
        script -->|"ref(0)"| refimpl["RefImpl { value: 0 }"]
        render -->|"读取 count.value"| track["track() 收集依赖"]
        click["用户点击"] -->|"count.value++"| trigger["trigger() 触发更新"]
        trigger -->|"调度渲染副作用"| rerender["重新执行渲染函数"]
        rerender -->|"diff + patch"| dom["更新真实 DOM"]
    end
    track -.->|"dep 记录 ReactiveEffect"| trigger

Der Schlüssel an diesem Diagramm ist:Es gibt nur zwei Kopplungspunkte zwischen den Compile-Zeit-Artefakten und dem Laufzeitverhalten——ref(0)das zurückgegebene RefImpl-Objekt sowie das Lesen und Schreiben voncount.valuein der Render-Funktion. Das bedeutet, wenn du einen bestimmten Zweig des Reaktivitätssystems debuggen möchtest (zum Beispieltriggerdie Scheduling-Logik in), musst du nur in diesemApp.vuedas entsprechende Lese-/Schreibmuster konstruieren.

Designüberlegung: Warumrefstattreactive？

---

Zwei, Alias-Auflösung:vite.config.tsundpackage.jsonwie man'vue'auf den lokalen Quellcode zeigt

Intuitives Modell

vite.config.tshat nur sechs Zeilen, aber es ist das „Routing-Zentrum“ der gesamten Sandbox – es entscheidet, obimport { createApp } from 'vue'in'vue'letztendlich die veröffentlichte Version von npm lädt oder den Quellcode, der sich im Repository in Entwicklung befindet. Ohne die richtige Alias-Konfiguration könnte der Code, den du inApp.vueänderst, möglicherweise überhaupt nicht den Vue-Quellcode auslösen, den du gerade debuggst, und das Debugging wird zu „auf das falsche Ziel schießen“.

Datenstruktur und Auflösungskette

Schauen wir zuerst aufvite.config.ts：

📎 packages-private/vite-debug/vite.config.ts:4-6

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
})

Hiergibt es keine expliziteresolve.alias-Konfiguration. Wie wird also'vue'zum lokalen Quellcode aufgelöst? Die Antwort liegt inpackage.json:

📎 packages-private/vite-debug/package.json:1-15

{
  "name": "vite-debug",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "serve": "vite preview"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "catalog:",
    "vite": "catalog:",
    "vue": "workspace:*"
  }
}

Der Schlüssel liegt inL13："vue": "workspace:*". Dies ist die Deklaration des pnpm-Workspace-Protokolls und bedeutet, dassvite-debugvon dem lokalen Paket namensvueim Monorepo abhängt und nicht von der Version in der npm-Registry. pnpm erstellt innode_modules/vueeinen symbolischen Link, der aufpackages/vuezeigt (das Hauptpaketverzeichnis von Vue).

Aber das reicht noch nicht –packages/vueinpackage.jsondasmain/module/exports-Feld zeigt normalerweise aufBuild-Artefakte(wiedist/vue.runtime.esm-bundler.js) und nicht auf den Quellcode untersrc/. Wenn dupackages/runtime-core/src/renderer.tsänderst, aber nicht neu baust, lädt Vite weiterhin die altedist-Datei.

Szenariogesteuerter Walkthrough: Einimport 'vue'Auflösungsprozess

In das Szenario eintauchen:Wenn der Vite-Dev-Server die Anfrage des Browsers nachmain.tserhält und aufimport { createApp } from 'vue'trifft, wie sieht dann die Auflösungskette aus?

flowchart TD
    req["浏览器请求 /main.ts"] --> parse["Vite 解析 import 'vue'"]
    parse --> resolve{"resolve 条件匹配"}
    resolve -->|"development 条件命中"| src_entry["packages/vue/src/index.ts"]
    resolve -->|"仅 production 条件"| dist_entry["packages/vue/dist/vue.runtime.esm-bundler.js"]
    src_entry -->|"源码模块图"| hmr["HMR 监听 src/ 变更"]
    dist_entry -->|"预构建产物"| no_hmr["无源码级 HMR"]
    hmr -->|"修改 renderer.ts"| reload["浏览器热更新"]
    no_hmr -->|"修改 renderer.ts"| stale["仍加载旧产物"]
    reload --> verify["验证行为变更"]
    stale --> rebuild["需手动重新构建"]
    rebuild --> verify

Dieses Flussdiagramm offenbart einen entscheidenden Zweig:Wenn diedevelopment-Bedingung nicht korrekt konfiguriert ist, wird der Browser nach Änderungen am Quellcode nicht hot-updaten, und du gerätst in die Verwirrung „Code geändert, aber Verhalten unverändert“. Die Fehlersuche besteht darin, im Network-Panel der Browser-DevTools den tatsächlichen Ladepfad desvue-Moduls zu prüfen – wenn du dendist/-Pfad siehst, bedeutet das, dass das Quellcode-Einstiegsmapping nicht wirksam ist.

Designüberlegung: Warum nicht invite.config.tsexplizit einen Alias schreiben?

1. Es zerstört Subpfad-Importe: Die öffentliche API von Vue enthältvue/server-renderer、vue/compiler-sfcund andere Subpfade. Wenn nur'vue'selbst aliast wird, laufen Subpfad-Importe weiterhin überdist, was dazu führt, dass einige Module aus dem Quellcode und andere aus den Build-Artefakten stammen, mit inkonsistentem Verhalten.

2. Es umgeht den bedingten Exportmechanismus: In Vuespackage.jsonhat dasexports-Feld bereits ein vollständiges bedingtes Export-Mapping definiert (development/production/browser/nodeusw.), und der Alias würde diesen Mechanismus überschreiben, sodass die Auflösung im Debugging-Umfeld von der im echten Benutzerumfeld abweicht.

Dahervite-debugwähltpackage.jsondie Kombination „Workspace-Protokoll vertrauen + bedingte Exporte“, um die Auflösungskette so nah wie möglich am realen Nutzungsszenario zu halten. Das erklärt auch, warum"vue": "workspace:*"innode_modules/vueerforderlich ist – es ist die Voraussetzung dafür, den pnpm-Symlink auszulösen und Vite dadurchpackages/vuefinden zu lassen.

Produktions-Fallstricke:catalog:Protokoll- und Versionsdrift

Beachtepackage.jsoninL11-L12verwendet das"catalog:"-Protokoll:

"@vitejs/plugin-vue": "catalog:",
"vite": "catalog:",

Dies ist eine pnpm-Catalog-Funktion und bedeutet, dass die Versionsnummer zentral über daspnpm-workspace.yaml-Feld incatalogverwaltet wird. Ihre Aufgabe ist es,Versionsdrift zu vermeiden, wenn im Monorepo mehrere Pakete dieselbe Abhängigkeit referenzieren。

---

Drei,packages-privateIsolationsdesign: Warum die Debug-Sandbox nicht veröffentlicht wird

Intuitives Modell

packages-privateDas Verzeichnis ist wie ein „internes Labor" eines Unternehmens – die darin enthaltenen Muster werden nicht extern verkauft, sondern nur für Tests und Demonstrationen verwendet. Es ist physisch vompackagesVerzeichnis isoliert, um zu verhindern, dass Debug-Code versehentlich auf npm veröffentlicht wird.

Drei Schutzschichten des Isolationsmechanismus

Erste Schicht: Verzeichnisisolation

packages-private/vite-debugbefindet sich nicht unterpackages/, währendpnpm-workspace.yamlnormalerweise sowohlpackages/*als auchpackages-private/*als Workspace-Mitglieder deklariert, aber das Veröffentlichungsskript (z. B.scripts/release.js) nur die Pakete unterpackages/durchläuft.

Zweite Schicht:private: true

📎 packages-private/vite-debug/package.json:3

"private": true,

Diese Zeile ist eine harte Einschränkung von npm/pnpm: Pakete, die alsprivatemarkiert sind,können niemals durchnpm publishveröffentlicht werden, selbst bei manueller Ausführung wird dies abgelehnt. Dies ist die letzte Verteidigungslinie gegen versehentliche Veröffentlichung.

Dritte Schicht: Keinversion-Feld

Beachten Sie, dasspackage.jsonkeinversion-Feld enthält. Die npm-Spezifikation verlangt, dass veröffentlichbare Paketeversionhaben müssen; Pakete ohne dieses Feld führen beinpm publishzu einem Fehler. Dies ist eine „doppelte Absicherung" – selbst wennprivateversehentlich gelöscht wird, verhindert das fehlendeversionweiterhin die Veröffentlichung.

Designüberlegung: Arbeitsteilung zwischen Debug-Sandbox und Playground

Im Vue-Core-Repository gibt es bereits einen voll funktionsfähigenSFC Playground(in Kapitel 7 diskutiert). Warum wird dann nochvite-debug？

vite-debugDer Kernwert vonliegt darin, dass es in einer echten Node.js-Umgebung läuft, man kann mitnode --inspecteinen Debugger anhängen, inpackages/reactivity/src/effect.tsBreakpoints setzen und den Erstellungs- und Scheduling-Prozess vonReactiveEffectbeobachten. Dies kann der Playground nicht bieten.

Produktions-Fallstricke: HMR-Grenzen und Zustandsverlust

Eine weitere Falle: Wenn Sie den Quellcode unterpackages/runtime-core/src/ändern, wird die HMR-Propagierungskette möglicherweise nicht automatisch ausgelöst – weilvite-debugdie HMR-Grenze auf der Ebene vonApp.vuedefiniert ist, während Quellcode-Änderungen unterpackages/durch Vites Modulgraph propagiert werden müssen. Wenn der Browser nach einer Quellcode-Änderung nicht reagiert, prüfen Sie die Vite-Terminalausgabe aufhmr update-Logs; falls keine vorhanden sind, muss möglicherweise der Dev-Server neu gestartet werden.

---

Kapitelzusammenfassung

packages-private/vite-debugMit vier Dateien und weniger als 40 Zeilen Code wird ein vollständiger Debug-Kreislauf aufgebaut:

1. main.tsBietet eine minimale Mount-Kette:createApp(App).mount('#app'), unter Ausschluss jeglicher nicht notwendiger Initialisierungslogik.

2. App.vueAls Experimentträger:ref+ Template-Interpolation + Event-Handling, deckt den Hauptpfad des Reaktivitätssystems ab.

3. vite.config.ts + package.jsonDurch dasworkspace:*-Protokoll und bedingte Exporte wird'vue'auf den lokalen Quellcode aufgelöst, wodurch „Quellcode-Änderung sofort wirksam" erreicht wird.

4. packages-private + private: true+ keinversionDreischichtige Isolation, um sicherzustellen, dass Debug-Code nicht versehentlich veröffentlicht wird.

Die Ingenieursphilosophie dieser Sandbox ist:Die Komplexität der Debug-Umgebung selbst sollte gegen null gehen, die gesamte Komplexität dem zu debuggenden Quellcode überlassen. Wenn Sie inpackages/reactivityauf einen schwer reproduzierbaren Bug stoßen,vite-debugbietet

eine Experimentierplattform, die beliebig geändert und sofort verifiziert werden kann.

---

Das Größenbudget sagt dir „Das Problem existiert“,vite-debuglässt dich „das Problem selbst reproduzieren“. Aber wenn du versuchst, dieses Sandbox-Muster auf das gesamte Monorepo zu übertragen, stößt du auf eine Reihe von Randbedingungen: Unterschiede bei der Auflösung des Workspace-Protokolls in CI-Umgebungen,catalog:das Upgrade-Dilemma der Versionssperrung,packages-privateundpackagesdie Richtungsbeschränkung der Abhängigkeiten zwischen... Das nächste Kapitel behandelt Architektur-Abwägungen und Fallstrick-Vermeidung und systematisiert die Randbedingungen, die die Monorepo-Engineering in realen Projekten offenlegt.

Damit haben wir den Engineering-Kreislauf von der Größenmessung bis zur minimalen Reproduktion abgeschlossen: vite-debug macht mit minimalistischen vier Dateien „schnelle Validierung am echten Quellcode“ zu einer alltäglich nutzbaren Praxis. Doch wenn du beginnst, dieses System wirklich nachzubauen, wirst du weitere verborgene Abwägungen entdecken – warum muss packages-private physisch von packages getrennt sein? Warum muss das Enum-Inlining vor Rollup abgeschlossen sein? Das nächste Kapitel fasst die entscheidenden Entscheidungspunkte und Produktions-Fallstricke aus den ersten zwölf Kapiteln zusammen und bietet dir eine vollständige Checkliste zur Fallstrick-Vermeidung und Entscheidungsgrundlage.

Im vorherigen Kapitel haben wir mitpackages-private/vite-debugals Einstieg das Debugging-Paradigma der minimalen Reproduktion am echten Quellcode gemeistert. Wenn solche internen Debug-Pakete immer mehr werden, taucht ein reales Problem auf: Sie teilen sich denselben Workspace mit den offiziell veröffentlichten Paketen – wie stellt man sicher, dass der Release-Prozess sie nicht versehentlich beeinträchtigt? Dieses Kapitel geht tief in die Randbedingungen der Monorepo-Engineering ein, ausgehend vom Doppelverzeichnis-Vertrag vonpackagesundpackages-private, analysiert die defensiven Designentscheidungen hinter den Architektur-Abwägungen und gibt umsetzbare Hinweise zur Fallstrick-Vermeidung.

13.2 Zeitliche eiserne Regel: Enum-Inlining muss vor Rollup ausgeführt werden

Intuitives Modell

Enum-Inlining ist wie „vor dem Verpacken die Etiketten auf den Teilen durch Zahlen ersetzen“. Wenn der Verpackungsarbeiter (Rollup) bereits mit dem Packen begonnen hat und du dann die Etiketten änderst, passen die Teile in der Kiste und die Etiketten nicht mehr zusammen.build.jsverwendetscanEnums() / removeCache()dieses Funktionspaar, um das Inlining strikt vor Rollup einzuklemmen.

Datenstruktur und Lebenszyklus

inline-enums.jsexportiertscanEnums()gibt eineremoveCacheClosure zurück, die Enum-Definitionen im Quellcode scannt und temporäre Dateien für Rollup zur Konsumption generiert📎 scripts/build.js:30-34。build.jsvonrun()verwendettry/finallyum die Cache-Bereinigung sicherzustellen📎 scripts/build.js:81-112：

const removeCache = scanEnums()
try {
  // ... buildAll / checkAllSizes / build-dts
} finally {
  removeCache()
}

rollup.config.jsruft auf ModulebeneinlineEnums()auf, um[enumPlugin, enumDefines] 📎 rollup.config.js:47-50zu erhalten, wobeienumPluginin das plugins-Array eingefügt wird📎 rollup.config.js:331-331，enumDefinesund in die Ersetzungstabelle des replace-Plugins aufgenommen wird📎 rollup.config.js:222-223。

Step-by-Step: Der vollständige Lebenszyklus eines Enums in einem Build

1. build.jsvonrun()ruft zuerstscanEnums()auf, scannt die Enum-Definitionen aller Pakete und schreibt sie in den temporären Cache, gibt zurückremoveCache 📎 scripts/build.js:87-87。

2. buildAllstartet mehrere Rollup-Prozesse parallel📎 scripts/build.js:119-121。

3. Jeder Rollup-Prozess führt in der KonfigurationsladephaseinlineEnums()aus, liest den im vorherigen Schritt generierten Cache und erhältenumPluginundenumDefines 📎 rollup.config.js:47-50。

4. enumPluginersetzt in der Transform-Phase Enum-Referenzen im Quellcode durch Literale;enumDefinesergänzt replace und behandelt modulübergreifende Konstantenersetzung📎 rollup.config.js:222-223。

5. Build endet,finallyBlock ruftremoveCache()auf, um temporäre Dateien zu bereinigen📎 scripts/build.js:119-121。

flowchart LR
  src["源码 enum 定义"] --> scan["scanEnums()<br/>scripts/inline-enums.js"]
  scan --> cache["临时缓存文件"]
  cache --> inline["inlineEnums()<br/>rollup.config.js"]
  inline --> plugin["enumPlugin<br/>transform 阶段替换"]
  inline --> defines["enumDefines<br/>replace 替换表"]
  plugin --> bundle["Rollup 产物<br/>字面量已内联"]
  defines --> bundle
  bundle --> cleanup["removeCache()<br/>finally 块"]

Designüberlegungen und Fallstricke

Produktions-Fallstrick:removeCache()infinallyzu platzieren bedeutet, dass auch bei einem Fehler mitten im Build bereinigt wird. Aber wenn du beim Debuggen den Prozess manuell unterbrichst (Ctrl+C),finallymöglicherweise nicht ausgeführt wird, und zurückbleibende Cache-Dateien dazu führen, dass der nächste Build veraltete Enums liest. Fehlersuche: Prüfen, ob imtemp/-Verzeichnis zurückbleibende Enum-Cache-Dateien vorhanden sind, manuell löschen und erneut versuchen.

---

13.3 Release-Orchestrator:release.jsdie Skip-Flag-Matrix von

Intuitives Modell

release.jsist wie der Hochzeitsregisseur,skipBuild / skipTests / skipGit / skipPromptsdie vier Schalter sind die Buttons für „Probe überspringen“, „Eid überspringen“, „Fotos überspringen“, „Bestätigung überspringen“. Jeder Button entspricht einem realen Szenario: CI-Umgebungen benötigenskipPrompts, lokales Debugging benötigtskipGit, dringende Hotfixes benötigenskipTests。

Datenstruktur und Standardwerte der Flags

Die vier Skip-Flags werden inparseArgsdeklariert📎 scripts/release.js:39-50und anschließend in lokale Variablen destrukturiert📎 scripts/release.js:64-66：

let skipTests = args.skipTests
const skipBuild = args.skipBuild
const skipPrompts = args.skipPrompts
const skipGit = args.skipGit

BeachteskipTestsverwendetletDeklaration, da sie inrunTestsIfNeeded()dynamisch umgeschrieben wird📎 scripts/release.js:281-317。

Step-by-Step: Der vollständige Entscheidungsfluss eines Releases

main()die Ausführungsreihenfolge📎 scripts/release.js:143-279：

1. Remote-Synchronisationsprüfung：isInSyncWithRemote()Vergleicht lokalen HEAD mit dem Remote-Branch-SHA und zeigt bei Abweichung einen Bestätigungsdialog an📎 scripts/release.js:337-363。

2. Versionsauswahl: Ohne Positionsargument wirdversionIncrementsAuswahlmenü angezeigt📎 scripts/release.js:152-176。

3. Testentscheidung：runTestsIfNeeded()ist der Bereich mit der dichtesten skip-Logik📎 scripts/release.js:281-317。

4. Versionsaktualisierung：updateVersions()Durchläuft alle Pakete und schreibtpackage.json 📎 scripts/release.js:377-398。

5. Changelog-Generierung: Ruft aufpnpm run changelog 📎 scripts/release.js:211-212。

6. Git-Commit：skipGitWird bei Wahrheit vollständig übersprungen📎 scripts/release.js:231-240。

7. Veröffentlichung: Nur wennargs.publishwahr ist, wird ausgeführtbuildPackages() + publishPackages() 📎 scripts/release.js:243-246。

runTestsIfNeeded()Die Branch-Logik verdient eine separate Betrachtung:

flowchart TD
  entry["runTestsIfNeeded()"] --> skipFlag{"skipTests?"}
  skipFlag -->|是| done["Tests skipped"]
  skipFlag -->|否| ci["getCIResult()"]
  ci --> ciPass{"CI passed?"}
  ciPass -->|是| promptMode{"skipPrompts?"}
  promptMode -->|是| setSkip["skipTests = true"]
  promptMode -->|否| ask["prompt: Skip local tests?"]
  ask --> setSkip2["skipTests = promptSkipTests"]
  ciPass -->|否| noPrompt{"skipPrompts?"}
  noPrompt -->|是| throwErr["throw Error<br/>CI not passed"]
  noPrompt -->|否| runLocal["run('pnpm', ['run','test','--run'])"]
  setSkip --> done
  setSkip2 --> done
  runLocal --> done

Designüberlegungen und Fallstricke

Der versteckte Vertrag der Veröffentlichungsreihenfolge：sortPackagesForPublishingPlatziertvuean letzter Stelle📎 scripts/release.js:85-85, und der Kommentar stellt ausdrücklich klar: „Benutzer dürfen das neue Einstiegspaket nicht installieren, bevor die internen Pakete verfügbar sind." Wenn Sie diese Reihenfolge ändern, könnte der Benutzer beinpm install vue@nexteine Version beziehen, deren Abhängigkeiten noch nicht veröffentlicht sind, was zuERR_MODULE_NOT_FOUND。

Idempotenzschutz：publishPackageRuft vor der VeröffentlichungisPackagePublishedauf, um die Registry zu prüfen📎 scripts/release.js:453-458, fängt bei Veröffentlichungsfehlernpreviously publishedFehler ab und degradiert zum Überspringen von📎 scripts/release.js:480-488. Dadurch kann das Release-Skript sicher wiederholt werden – nach einer Netzwerkunterbrechung schlägt die erneute Ausführung nicht wegen „Paket existiert bereits" vollständig fehl.

Fehler-Rollback：fnToRun().catch()Ruft auf, wennversionUpdatedwahr istupdateVersions(currentVersion)Rollt die Versionsnummer zurück📎 scripts/release.js:528-537. Beachten Sie jedoch: Dies rollt nurpackage.jsondas Versionsfeld inzurück,git commitsetzt bereitsCommits nicht zurückskipGit. Wenn Sie beigit reset。

---

als falsch die Veröffentlichung fehlschlägt, müssen Sie manuell

Designüberlegung: Das gemeinsame Muster der drei AbwägungenBetrachtet man die drei Kernabwägungen dieses Kapitels, teilen sie dieselbe Designphilosophie:。

• packages-private„Leicht vergessliche Laufzeitprüfungen" in „unmöglich zu umgehende strukturelle Constraints" umwandelnprivatePhysische Isolation: Es wird nicht darauf vertraut, dass der Skriptautor daran denkt,
• das Feld zu prüfen, sondern der Scan-Bereich schließt es von Natur aus aus.
• release.jsEnum-Inlining-Vorverlagerung: Es wird nicht darauf vertraut, dass das Rollup-Plugin beim Transform „zufällig" paketübergreifende Enums sieht, sondern vor dem Build ein globaler Cache aufgebaut.skipTests。

---

die Kreuzkombinationen der vier skip-Flags müssen behandelt werden. Doch für ein Repository wie Vue, das mehrmals wöchentlich veröffentlicht, überwiegt der Zuverlässigkeitsgewinn durch strukturelle Constraints bei Weitem die Komplexitätskosten.

Kapitelzusammenfassung

1. packages-privateDieses Kapitel hat ausgehend vom Quellcode drei entscheidende Randbedingungen des Vue-Core-Engineering-Systems herausgearbeitet:packagesDie physische Isolation vonundbuild.jswird durch drei Stellen gemeinsam gewährleistet: Workspace-Glob,release.jsVerzeichniserkennung,📎 pnpm-workspace.yaml:1-3📎 scripts/build.js:153-170📎 scripts/release.js:68-83。

2. FilterungDie Zeitliche Constraint des Enum-InliningsscanEnums() / removeCache()wird durchtry/finallydie📎 scripts/build.js:81-112📎 rollup.config.js:47-50。

3. release.jsStruktur vonerzwungen, die Rollup-Konfiguration konsumiert den Cache auf ModulebeneskipTestsDie skip-Flag-Matrix von📎 scripts/release.js:281-317📎 scripts/release.js:85-85。

dient drei Szenarien: CI-Release, lokales Debugging und Notfall-Hotfix,

Doppelverzeichnis-Vertrag, Zuordnungsentscheidung von Build-Skripten, Sekundärfilterung von Release-Skripten – diese Mechanismen zusammen definieren die Sicherheitsgrenzen der Monorepo-Industrialisierung. Doch Grenzen sind nicht statisch: Mit der Migration der Build-Tools von Rollup zu Rolldown und der Verschmelzung von Typtests und Laufzeittests werden die bestehenden Abwägungsstrategien vor neuen Herausforderungen stehen. Im nächsten Kapitel werden wir basierend auf dem Änderungsverlauf von 3.0 bis 3.4 die Entwicklungsrichtung der nächsten Generation des Industrialisierungssystems skizzieren.

Im vorherigen Kapitel haben wir die „Sicherheitsgrenzen" des Vue-Core-Industrialisierungssystems herausgearbeitet – Doppelverzeichnis-Vertrag, Zuordnungsentscheidung von Build-Skripten, Sekundärfilterung von Release-Skripten. Diese Mechanismen wurden nicht in einem Zug entworfen, sondern in den Iterationen von 3.0 bis 3.4 wiederholt geschliffen. Dieses Kapitel wechselt die Perspektive: Wir schauen nicht mehr darauf, „wie es jetzt aussieht", sondern darauf, „wie es zu dem geworden ist, was es jetzt ist", und leiten daraus ab, wohin die nächste Generation des Industrialisierungssystems steuern wird. Das Quellmaterial dieses Kapitels sind changelogs/CHANGELOG-3.3.md, changelogs/CHANGELOG-3.4.md sowie die package.json im Repository-Stammverzeichnis. Änderungsprotokolle scheinen nur eine Aufzählung von „welcher Bug wurde behoben" zu sein, aber sie sind der ehrlichste Gesundheitsbericht des Industrialisierungssystems: Jeder Commit mit dem Präfix build:, jede Änderung mit dem Präfix types:, jeder Rückzug einer Abhängigkeitsversion legt die Spannungspunkte der aktuellen Architektur offen. Unsere Aufgabe ist es, aus diesen Spannungspunkten die Entwicklungsrichtung herauszulesen. Das Änderungsprotokoll als „Beobachtungsfenster des Industrialisierungssystems" statt als „Funktionsliste" zu betrachten, ist die Kernmethodik dieses Kapitels. Funktionsänderungen sagen uns, was Vue leisten kann, während Änderungen an Build, Typen und CI uns sagen, „wo es weh tut" im Industrialisierungssystem von Vue.

I. Spannungspunkte der Build-Toolchain: Das Migrationspotenzial von Rollup zu Rolldown

Intuitives Modell

Stellen Sie sich die Build-Toolchain als eine Montagelinie vor: Rollup ist der Hauptmontagetisch, esbuild übernimmt das schnelle Schneiden (Transpilieren von TS), terser übernimmt das abschließende Bündeln und Komprimieren. Wenn das Produkt (die Vue-Laufzeit) immer komplexer wird und die Arbeitsschritte am Montagetisch zunehmen, wird der Hauptmontagetisch selbst zum Engpass. Die Positionierung von Rolldown ist der in Rust neu geschriebene Hauptmontagetisch – er soll nicht esbuild ersetzen, sondern Rollup selbst.

Ohne diesen Evolutionsdruck wäre die „Katastrophe", der das System gegenübersteht, nicht ein Absturz, sonderndie lineare Aufblähung der Build-Zeit mit der Anzahl der Pakete: Für jedes zusätzliche Unterpaket muss ein weiterer Rollup-Prozess gestartet, der Enum-Cache erneut durchsucht und eine weitere Runde der dts-Generierung durchlaufen werden.

Datenstrukturen und Abhängigkeitslayout

Betrachten wir zunächst einen statischen Schnappschuss der aktuellen Toolchain.package.jsonDiedevDependenciesvon ist eine präzise „Montagetisch-Liste":

📎 package.json:103-106

    "rollup": "^4.63.3",
    "rollup-plugin-dts": "^6.5.1",
    "rollup-plugin-esbuild": "^6.2.1",
    "rollup-plugin-polyfill-node": "^0.13.0",

Hier lassen sich drei Schlüsselfakten ablesen. Erstens ist die Rollup-Hauptversion^4.63.3, was sich in der Reifephase von Rollup 4.x befindet. Zweitens übernimmtrollup-plugin-esbuilddie TS-Transpilierung, was bedeutet, dass Rollup selbst kein TS parst, sondern nur das von esbuild ausgegebene JS verarbeitet. Drittens istrollup-plugin-dtsunabhängig verantwortlich für das.d.tsBundling, was genau die materielle Grundlage für diedts-built-testUnabhängigkeit ist, die im vorherigen Kapitel diskutiert wurde.

Betrachten wir nun die Einstiegsorchestrierung des Build-Skripts:

📎 package.json:8-9

    "build": "node scripts/build.js",
    "build-dts": "tsc -p tsconfig.build.json --noCheck && rollup -c rollup.dts.config.js",

build-dtsist „zweistufig": Zuersttsc --noCheckwerden rohe Deklarationsdateien generiert (--noChecküberspringt die Typprüfung und führt nur emit aus), dann werden mitrollup -c rollup.dts.config.jsdie verstreuten.d.tszu einer einzigen Datei gebündelt. Dieses Design selbst ist eine Abhängigkeit von den Fähigkeiten von Rollup –rollup-plugin-dtsbenötigt den Modulgraphen von Rollup, um Typabhängigkeiten zu verfolgen.

Szenariogetrieben: Was einbuild:-Commit offengelegt hat

Die Einträge mit dem Präfixbuild:im Änderungsprotokoll sind direkte Belege für die Spannungspunkte der Build-Toolchain. Wir greifen drei heraus.

Der erste, die minify-Konfigurationsangleichung in 3.4.32:

📎 changelogs/CHANGELOG-3.4.md:84

* **build:** use consistent minify options from previous terser config ([789675f](https://github.com/vuejs/core/commit/789675f65d2b72cf979ba6a29bd323f716154a4b))

Die Motivation dieses Commits war „inkonsistente Komprimierungsoptionen nach der Migration von terser zu esbuild minify". Er offenbart einen Zwischenzustand während der Migration: Vue verwendete einst terser zur Komprimierung, wechselte später zu esbuild (was durchdevDependenciesinesbuild: ^0.28.2bestätigt wird), aber die Komprimierungsoptionen wurden nicht vollständig angeglichen, was zu Abweichungen bei der Produktgröße oder im Verhalten führte. Genau das sind die typischen Kosten beim „Austausch von Montagetisch-Komponenten".

Der zweite, der entities-Versionsrückzug in 3.4.38:

📎 changelogs/CHANGELOG-3.4.md:6

* **build:** revert entities to 4.5 to avoid runtime resolution errors ([f349af7](https://github.com/vuejs/core/commit/f349af7b65b9f8605d8b7bafcc06c25ab1f2daf0)), closes [#11603](https://github.com/vuejs/core/issues/11603)

entitiesist eine HTML-Entity-Dekodierungsbibliothek, die voncompiler-domabhängt. Der Rückzug auf 4.5 erfolgte, weil die neue Version Probleme bei der Laufzeitanalyse verursachte. Dieser Commit zeigt:Die Abhängigkeitsaktualisierung der Build-Toolchain ist nicht isoliert; ein Versionssprung einer indirekten Abhängigkeit kann bis in das Laufzeitverhalten durchschlagen。

Der dritte, die cjs-Build-Kontamination des server-renderer in 3.4.29:

📎 changelogs/CHANGELOG-3.4.md:155

* **build:** fix accidental inclusion of runtime-core in server-renderer cjs build ([11cc12b](https://github.com/vuejs/core/commit/11cc12b915edfe0e4d3175e57464f73bc2c1cb04)), closes [#11137](https://github.com/vuejs/core/issues/11137)

Dies ist die typischste Art von Build-Bug: Im CJS-Format hatserver-rendererversehentlichruntime-corein sein eigenes Produkt eingebunden. Die Ursache ist normalerweise, dass dieexternal-Bestimmung von Rollup im CJS-Format versagt – ESM kann externe Abhängigkeiten statisch durchimport-Anweisungen erkennen, während CJSrequireDynamik ist stärker, leicht zu übersehen. Dieser Commit zeigt direkt auf die Anfälligkeit der Logik in der Rollup-Konfiguration.externalLogik.

Mermaid-Darstellung des Migrationspotenzials

Das folgende Diagramm stellt den Kontrollfluss der aktuellen Build-Pipeline dar und markiert die Knoten, die von der Rolldown-Migration betroffen sein werden:

flowchart TD
    start["node scripts/build.js"] --> scan["scanEnums() 全局扫描"]
    scan --> cache_ok{"enum 缓存就绪?"}
    cache_ok -->|否| err_enum["抛出错误 / 中断构建"]
    cache_ok -->|是| build_all["buildAll() 并发启动"]
    build_all --> rollup_proc["每个包一个 Rollup 进程"]
    rollup_proc --> inline["inlineEnums() 顶层调用"]
    inline --> esbuild_plugin["rollup-plugin-esbuild 转译 TS"]
    esbuild_plugin --> external_check{"external 判定"}
    external_check -->|ESM 格式| ext_ok["静态 import 识别成功"]
    external_check -->|CJS 格式| ext_risk["require 动态性导致漏判"]
    ext_risk --> pollution["runtime-core 被打进 server-renderer"]
    ext_ok --> output["产物输出"]
    pollution --> output
    output --> dts["build-dts 两段式生成"]
    dts --> tsc_emit["tsc --noCheck 生成原始 d.ts"]
    tsc_emit --> rollup_dts["rollup-plugin-dts 打包"]
    rollup_dts --> done["构建完成"]

Design-Überlegungen und Fallstricke

Warum wird die Migration nicht auf einen Schlag erfolgen?Betrachten Siepackage.jsonDasenginesFeld:

📎 package.json:61-63

  "engines": {
    "node": ">=20.0.0"
  },

Node 20 ist die harte Untergrenze. Rolldown als Rust-natives Modul benötigt entsprechende N-API-Bindings und vorkompilierte Binärverteilung. Sobald es eingeführt wird,pnpm installDie Zeitaufwände, die plattformübergreifende (Windows/macOS/Linux) Binärkompatibilität und die CI-Cache-Strategie müssen neu gestaltet werden. Das ist nicht einfach „eine Abhängigkeit austauschen", sondernEine Neukalibrierung der gesamten Installations-Build-Cache-Kette。

Produktions-Fallstricke：build-dtsDastsc --noCheckIst ein zweischneidiges Schwert. Das Überspringen der Typprüfung beschleunigt das Emit, bedeutet aber, dass.d.tsIn der Generierungsphase keine Typfehler entdeckt werden – Typfehler können nur durchpnpm check（tsc --incremental --noEmit) undtest-dtsAufgefangen werden. Wenn nach der Rolldown-Migration diese beiden Schritte zusammengeführt werden sollen, muss sichergestellt werden, dass die Typprüfung den Build nicht verlangsamt, sonst widerspricht dies der ursprünglichen Absicht von--noCheck.

---

Zwei, der Fusionstrend von Typtests und Laufzeittests

Intuitives Modell

Stellen Sie sich Typtests und Laufzeittests als zwei unabhängige Qualitätskontrollpunkte vor: Einer prüft, ob „die Bedienungsanleitung (.d.ts) korrekt geschrieben ist", der andere prüft, ob „die Maschine (Laufzeit) korrekt läuft". Beide Kontrollpunkte haben eigene Arbeitsplätze, eigene Werkzeuge und eigene Berichte. Der Fusionstrend bedeutet:Können dieselben Testfälle gleichzeitig die Bedienungsanleitung und die Maschine validieren?

Ohne Fusion steht das System vor der KatastropheDrift zwischen Typ und Laufzeitverhalten：.d.tsSagtref()Gibt zurückRef<T>, aber die tatsächlich zurückgegebene Objektform zur Laufzeit hat sich geändert, der Typtest besteht, der Laufzeittest besteht ebenfalls, aber die Kombination beider ist falsch.

Datenstruktur: Das Orchestrierungslayout der Testskripte

package.jsonInscriptsSind die testbezogenen Einträge klar in zwei Gruppen unterteilt:

📎 package.json:19-24

    "test": "vitest",
    "test-unit": "vitest --project unit*",
    "test-e2e": "node scripts/build.js vue -f global -d && vitest --project e2e --project e2e-browser",
    "test-dts": "run-s build-dts test-dts-only",
    "test-dts-only": "tsc -p packages-private/dts-built-test/tsconfig.json && tsc -p ./packages-private/dts-test/tsconfig.test.json",
    "test-coverage": "vitest run --project unit* --coverage",

Die Schlüsselstruktur hier isttest-dtsDasrun-s build-dts test-dts-only– es istSeriell: Zuerst wird.d.tsGebaut, dann werden die Typtests ausgeführt. Undtest-dts-onlyIst intern wiederumZwei unabhängigetscProzesse: Einer führtdts-built-testAus (validiert die Build-Artefakte), einer führtdts-testAus (validiert die Quellcode-Typen).

Beachten Sietest-unitVerwendetvitest --project unit*，test-e2eVerwendetvitest --project e2e --project e2e-browser. Dies zeigt, dass der--project-Mechanismus von Vitest die Tests bereits nach „Unit/E2E/Browser" in verschiedene Projekte aufgeteilt hat.Die physische Grundlage für die Fusion existiert bereits: Der Projekt-Mechanismus von Vitest erlaubt es, verschiedene Testtypen im selben Runner auszuführen.

Szenario-getrieben: Der vollständige Pfad einestypes:Commits

Im Änderungsprotokoll ist die Dichte der Einträge mit dem Präfixtypes:Extrem hoch, was die Komplexität des Typsystems direkt widerspiegelt. Wir verfolgen einen typischen Typ-Fix.

Der ref-Typ-Rückfall in 3.4.37:

📎 changelogs/CHANGELOG-3.4.md:23-24

* Revert "fix(types/ref): allow getter and setter types to be unrelated ([#11442](https://github.com/vuejs/core/issues/11442))" ([b1abac0](https://github.com/vuejs/core/commit/b1abac06cdb198bd72f8e614b1f68b92e1c78339))
* Revert "fix(types/ref): correct type inference for nested refs ([#11536](https://github.com/vuejs/core/issues/11536))" ([3a56315](https://github.com/vuejs/core/commit/3a56315f94bc0e11cfbb288b65482ea8fc3a39b4))

Zwei aufeinanderfolgende Reverts, die zwei Typ-Fixes zurückgerollt haben. Beachten Sie, dass diese beiden Fixes in 3.4.35 gerade erst gemergt wurden:

📎 changelogs/CHANGELOG-3.4.md:55

* **types/ref:** allow getter and setter types to be unrelated ([#11442](https://github.com/vuejs/core/issues/11442)) ([e0b2975](https://github.com/vuejs/core/commit/e0b2975ef65ae6a0be0aa0a0df43fb887c665251))

📎 changelogs/CHANGELOG-3.4.md:30

* **types/ref:** correct type inference for nested refs ([#11536](https://github.com/vuejs/core/issues/11536)) ([536f623](https://github.com/vuejs/core/commit/536f62332c455ba82ef2979ba634b831f91928ba)), closes [#11532](https://github.com/vuejs/core/issues/11532) [#11537](https://github.com/vuejs/core/issues/11537)

Vom Merge in 3.4.35 bis zum Revert in 3.4.37 liegt nur eine Patch-Version dazwischen. Dieser schnelle „Merge-Revert"-Zyklus offenbart ein grundlegendes Dilemma von Typtests:Typtests können validieren, dass „die Typsignatur den Erwartungen entspricht", aber sie können nicht validieren, ob „diese Typsignatur im echten Code gut nutzbar ist".。allow getter and setter types to be unrelatedIn Typtests kann es vollständig bestehen, aber in der tatsächlichen Verwendung wird die Typinferenz vonrefZu locker, was die Typsicherheit des nachgelagerten Codes beeinträchtigt.

Mermaid-Darstellung der Typtest-Fusion

Das folgende Diagramm stellt die aktuelle Trennstruktur von Typtests und Laufzeittests sowie die Zielform nach der Fusion dar:

flowchart LR
    subgraph current["当前：分离的两条链路"]
        src["packages/*/src/*.ts"] --> tsc_build["tsc -p tsconfig.build.json --noCheck"]
        tsc_build --> raw_dts["散落的 .d.ts"]
        raw_dts --> rollup_dts["rollup -c rollup.dts.config.js"]
        rollup_dts --> built_dts["打包后的 .d.ts"]
        built_dts --> dts_built_test["dts-built-test/tsconfig.json"]
        src --> dts_test["dts-test/tsconfig.test.json"]
        src --> vitest_unit["vitest --project unit*"]
        dts_built_test --> report_a["类型报告"]
        dts_test --> report_a
        vitest_unit --> report_b["运行时报告"]
    end
    subgraph future["融合目标：单一 runner"]
        src2["源码"] --> vitest_all["vitest --project unit --project dts"]
        vitest_all --> unified["统一报告 + 类型断言"]
    end
    current -.演进.-> future

Ist „vollständig", während die Tests von Vitest „dateiweise" sind – die inkrementellen Strategien beider sind inkompatibel.

Design-Überlegungen und Fallstrickedts-built-testWarumdts-test？Unabhängig vondts-built-testSein muss – wurde im vorherigen Kapitel bereits diskutiert, hier ergänzt aus evolutionärer Perspektive:Validiert（rollup-plugin-dtsBuild-Artefakte.d.ts），dts-testDas gepackteValidiertQuellcode-Typen

📎 changelogs/CHANGELOG-3.4.md:9

* **types:** add fallback stub for DOM types when DOM lib is absent ([#11598](https://github.com/vuejs/core/issues/11598)) ([4db0085](https://github.com/vuejs/core/commit/4db0085de316e1b773f474597915f9071d6ae6c6))

Kopierendts-built-test„Fallback-Stub bereitstellen, wenn DOM lib fehlt" – dies ist eine Typkompatibilitätskorrektur auf der Ebene der Build-Artefakte, die nur im Szenario von.d.ts, bei dem gepackte

Konsumiert werden, entdeckt werden kann.Produktions-Fallstricke: Der „Merge-Revert"-Zyklus von Typtests zeigt, dass Änderungen an TypsignaturenEchte nachgelagerte Projektepackages-private/dts-testwird ein repositoryinterner Testfall verwendet, der nicht alle nachgelagerten Nutzungsweisen abdeckt. Wenn der Fusionstrend nur darauf achtet, „zwei Runner zusammenzuführen“, ohne zu lösen, „wie echtes nachgelagertes Feedback eingebracht wird“, ist das nur eine formale Fusion.

---

Drei. Richtungen für feingranulare Optimierung des CI-Caches

Intuitives Modell

Stellen Sie sich den CI-Cache als „Materialbereich“ eines Repositorys vor: Jeder Build muss Rohmaterialien (Abhängigkeiten, Build-Artefakte, Typcache) aus dem Materialbereich entnehmen. Wenn der Materialbereich nur eine große Kiste hat und für jeden Gegenstand die gesamte Kiste durchsucht werden muss, kann selbst eine hohe Cache-Trefferrate nicht schnell sein. Feingranulare Optimierung bedeutet:Die große Kiste in kleine, nach Verwendungszweck kategorisierte Fächer aufteilen。

Ohne feingranularen Cache steht das System vor folgender Katastrophe:Kaskadierende Verstärkung von Cache-Invalidierung: Eine Zeile Quellcode ändern führt dazu, dass der gesamtenode_modules-Cache ungültig wird, CI alle Abhängigkeiten neu installiert und die Build-Zeit von 2 Minuten auf 10 Minuten steigt.

Datenstruktur: Klassifizierung cachefähiger Objekte

Auspackage.jsonlassen sich mehrere Arten cachefähiger „Materialien“ erkennen:

Erste Kategorie: Installationsartefakte von Abhängigkeiten.packageManagerDas Feld legt die pnpm-Version fest:

📎 package.json:4

  "packageManager": "pnpm@12.4.2",

pnpm'snode_modulesist eine Symlink-Struktur; gecacht wird der content-addressable Store von pnpm, nicht ein flachesnode_modules. Das bedeutet, der Cache-Schlüssel sollte auf dem Hash vonpnpm-lock.yamlbasieren, nicht aufpackage.json。

Zweite Kategorie: Build-Artefakte.cleanDas Skript offenbart die physischen Speicherorte der Artefakte:

📎 package.json:10

    "clean": "rimraf --glob packages/*/dist temp .eslintcache",

packages/*/dist、temp、.eslintcache— diese drei Arten von Artefakten können unabhängig gecacht werden.distist die Build-Ausgabe,tempsind temporäre Dateien (wiebench.json），.eslintcacheist der Lint-Cache.

Dritte Kategorie: Typprüfungs-Cache.checkDas Skript verwendet--incremental：

📎 package.json:15

    "check": "tsc --incremental --noEmit",

--incrementalerzeugt.tsbuildinfoDateien; dies ist der inkrementelle Cache der Typprüfung. Wenn diese Datei in CI gecacht wird,tscwird der zweite Lauf von

viel schneller sein.

Szenariogetrieben: CI-Ausführungsfluss eines PRspackages/reactivity/src/ref.tsIn ein typisches Szenario eintauchen: Ein Entwickler ändert

und reicht einen PR ein. Welche Schritte muss CI ausführen, und welche können den Cache treffen?scriptsAussimple-git-hookslässt sich die CI-Ausführungssequenz ableiten (pre-commit's

📎 package.json:48-51

  "simple-git-hooks": {
    "pre-commit": "pnpm lint-staged && pnpm check",
    "commit-msg": "node scripts/verify-commit.js"
  },

Kopierenpre-commitLokal läuftlint-stagedmitcheckundlint、check、test-unit、test-dts、size. In CI werden dann

• lintusw. ausgeführt. Die Cache-Strategie ist für jeden Schritt unterschiedlich:.eslintcache: cache
• check, Schlüssel basiert auf dem Hash der Quelldateien..tsbuildinfo: cachetsconfig, Schlüssel basiert auf
• test-unitund dem Quellcode-Hash.
• test-dts: Vitest hat einen eigenen Cache, aber üblicherweise werden in CI keine Testergebnisse gecacht, sondern nur Abhängigkeiten.build-dts: hängt von den Artefakten vonpackages/*/distab, Cache-Schlüssel basiert auf dem Hash von
• size: hängt von Build-Artefakten ab, Cache-Schlüssel wie oben.

Mermaid-Darstellung der CI-Cache-Optimierung

flowchart TD
    pr["PR 提交"] --> checkout["checkout 代码"]
    checkout --> cache_deps{"pnpm store 缓存命中?"}
    cache_deps -->|是| install_fast["pnpm install --offline"]
    cache_deps -->|否| install_slow["pnpm install 全量下载"]
    install_fast --> lint_step["pnpm lint"]
    install_slow --> lint_step
    lint_step --> cache_eslint{".eslintcache 命中?"}
    cache_eslint -->|是| lint_inc["增量 lint"]
    cache_eslint -->|否| lint_full["全量 lint"]
    lint_inc --> check_step["pnpm check"]
    lint_full --> check_step
    check_step --> cache_tsbuild{".tsbuildinfo 命中?"}
    cache_tsbuild -->|是| check_inc["增量类型检查"]
    cache_tsbuild -->|否| check_full["全量类型检查"]
    check_inc --> test_unit["pnpm test-unit"]
    check_full --> test_unit
    test_unit --> build_dts["pnpm build-dts"]
    build_dts --> cache_dist{"packages/*/dist 命中?"}
    cache_dist -->|是| dts_cached["复用 dts 产物"]
    cache_dist -->|否| dts_rebuild["重新生成 dts"]
    dts_cached --> test_dts["pnpm test-dts-only"]
    dts_rebuild --> test_dts
    test_dts --> size_check["pnpm size"]
    size_check --> done["CI 通过"]

Designüberlegungen und Stolperfallen

Warum muss dassize-Skript in mehrere Unterbefehle aufgeteilt werden?Betrachten Sie diese drei:

📎 package.json:11-14

    "size": "run-s \"size-*\" && node scripts/usage-size.js",
    "size-global": "node scripts/build.js vue runtime-dom -f global -p --size",
    "size-esm-runtime": "node scripts/build.js vue -f esm-bundler-runtime",
    "size-esm": "node scripts/build.js runtime-dom runtime-core reactivity shared -f esm-bundler",

sizeverwendetrun-s "size-*", um alle Unterbefehle mit dem Präfixsize-seriell auszuführen. Dieses „Präfix-Aggregations“-Muster ermöglicht es, jede Größen-Dimension (global, esm-runtime, esm) unabhängig zu cachen und unabhängig fehlschlagen zu lassen. Wenn man sie zu einem großen Befehl zusammenführt, lässt jede Dimensionsüberschreitung das gesamtesizefehlschlagen, und es lässt sich nicht lokalisieren, welches Problem welche Dimension betrifft.

Produktions-Stolperfallen: Die häufigste Falle bei CI-Caches istCache-Verschmutzung—falsche Artefakte werden gecacht, sodass spätere Builds auf schmutzigen Daten basieren.cleanDas

📎 package.json:10

    "clean": "rimraf --glob packages/*/dist temp .eslintcache",

Kopierenpackages/*/distBeachten Sie, dass espackages-private/*/distbereinigt, nichtpackages-private. Das bedeutet, die Artefakte vonpackages-privateliegen nicht im regulären Bereinigungsbereich—wenn CI die Artefakte voncleancacht undpackages-privatesie nicht bereinigt, kann das Problem entstehen, dass „alte Playground-Artefakte gecacht wurden“. Beim Design feingranularer Caches muss

---

separat behandelt werden.

Designüberlegung: Das Engineering-System als ProduktlebenszyklusWenn man die Hinweise der drei Abschnitte verbindet, erkennt man eine klare Hauptlinie:。

Das Engineering-System von Vue bewegt sich von „funktionsfähig“ zu „gut nutzbar“, von „manueller Orchestrierung“ zu „deklarativer Konfiguration“

Die Migration der Build-Toolchain (Rollup → Rolldown) ist eine „leistungsgetriebene“ Entwicklung: Wenn die Anzahl der Pakete bis zu einem gewissen Grad wächst, übersteigen die Kosten prozessbasierter Nebenläufigkeit den Nutzen, und es muss auf ein leichteres Nebenläufigkeitsmodell umgestellt werden.

Die Fusion von Typtests ist eine „konsistenzgetriebene“ Entwicklung: Wenn sich Typ-Signaturen häufiger ändern als das Laufzeitverhalten, werden zwei getrennte Testsätze zur Last, und sie müssen dieselben Testfälle gemeinsam nutzen.

---

-Abschnitt des Changelogs) erlaubt in Minor-Versionen „type-only breaking changes“, aber keine Laufzeit-Breaking-Changes. Das bedeutet, die Entwicklung des Engineering-Systems muss sicherstellen: Egal wie die interne Toolchain ausgetauscht wird, die öffentliche API und das Laufzeitverhalten der Artefakte dürfen sich nicht ändern. Dies ist die harte Grenze aller Entwicklungsentscheidungen.

Zusammenfassung dieses Kapitelspackage.jsonDieses Kapitel geht vom Changelog und

1. aus und ordnet die drei Entwicklungslinien des Engineering-Systems von Vue core:: Die aktuelle Kombination aus Rollup 4.x + esbuild + rollup-plugin-dts zeigt ihre Belastungspunkte inbuild:Commits mit dem Präfix (Minify-Konfigurationsabgleich, Entities-Versionsrücknahme, übersehene CJS-External-Erkennung). Das Potenzial der Rolldown-Migration liegt in der Ablösung von „Multi-Prozess-Konkurrenz" durch „Single-Prozess-Parallelität", der Widerstand kommt vom Plugin-Ökosystem und der plattformübergreifenden Binärverteilung.

2. Typentest-Fusion：test-dtsderrun-s build-dts test-dts-onlyserielle Struktur sowiedts-built-testunddts-testdie dualetscProzesse sind der physische Beweis für die aktuelle getrennte Form. Der technische Pfad zur Fusion nutzt Vitests--projectMechanismus, der Widerstand ist die Inkompatibilität zwischentscVollprüfung und Vitests dateibasierter inkrementeller Teststrategie.

3. CI-Cache-Feingranularisierung：packageManagerpnpm locken,cleandrei Arten von Artefakten bereinigen,checkmit--incremental、sizemit Präfix aggregieren – all dies sind Klassifizierungskriterien für cachebare Objekte. Der Kernwiderspruch ist die Granularität des Cache-Schlüssels, eine sinnvolle Strategie ist „Sharding nach Paket".

Der wichtigste kognitive Wandel ist:Das Engineering-System selbst ist ein Produkt, es hat seine eigenen Nutzer (Contributors), seine eigenen Leistungsmetriken (Build-Zeit, CI-Minuten), seine eigenen Kompatibilitätsbeschränkungen (Artefakt-API unverändert). Es erfordert kontinuierliche Iteration, nicht einmaliges Design.

Gedanken und Selbsttests dieses Kapitels

Durch das Beobachtungsfenster des Changelogs haben wir die Belastungspunkte des aktuellen Engineering-Systems identifiziert und daraus mögliche Entwicklungsrichtungen des nächsten Systems abgeleitet. Diese Richtungen sind keine Luftschlösser, sondern aus realen Produktions-Fallstricken und Abwägungen gewachsen. Damit endet die Analyse des Vue-Engineering-Systems in diesem Buch, aber die Erforschung des Engineerings kennt kein Ende – das nächste Kapitel wird als Schlusskapitel die Perspektive von Vue selbst wegziehen und untersuchen, wie diese Erfahrungen auf breitere Engineering-Szenarien übertragen werden können.