No capítulo anterior, esclarecemos a posição do repositório core como matriz de engenharia e como o pnpm workspace e as configurações no nível raiz restringem uniformemente todos os subpacotes. Agora, vamos nos aprofundar no núcleo do sistema de build e rastrear como um comando impulsiona todo o fluxo de build.node scripts/build.js vueparece simples, mas é a única entrada para todos os artefatos — esm-bundler, cjs, global. Entender como ele traduz a intenção do usuário em tarefas de build executáveis é um passo fundamental para dominar o mecanismo de build do Vue.

Geração da configuração Rollup: de variáveis de ambiente a artefatos em múltiplos formatos

build.jsviaexecinicia o Rollup, o controle passa pararollup.config.js. Este arquivo é o "cérebro" do sistema de build — ele lê variáveis de ambiente e gera dinamicamente um array de objetos de configuração Rollup.

Validação de variáveis de ambiente e localização de pacotes

📎 rollup.config.js:27-29

SeTARGETnão estiver definido, lança erro diretamente. Isso é programação defensiva: a configuração Rollup pode ser chamada diretamente (comorollup -c), e nesse momento não hábuild.jsinjetando variáveis de ambiente, então é preciso falhar rapidamente.

📎 rollup.config.js:32-44

Aqui se repete a lógica de determinação de pacote privado embuild.js— porquerollup.config.jsé um processo independente e não pode compartilhar o estado em memória debuild.js.resolveA função resolve caminhos relativos para caminhos absolutos dentro do diretório do pacote,pkgé o conteúdo depackage.jsondo pacote-alvo,packageOptionsé o campobuildOptionsdentro dele,nameé o prefixo do nome do arquivo de artefato (priorizabuildOptions.filename, caso contrário usa o nome do diretório).

Tabela de mapeamento de formatos:outputConfigs

📎 rollup.config.js:58-88

Esta tabela define o mapeamento de 7 formatos para configurações de saída. Observações-chave:

• esm-bundler、esm-browser、esm-bundler-runtime、esm-browser-runtimesão todosformat: 'es', a diferença está apenas no nome do arquivo.
• cjséformat: 'cjs'。
• globaleglobal-runtimeéformat: 'iife'(expressão de função imediatamente invocada), adequado para introdução direta via tag<script>.
• runtimeFormatos com sufixo só fazem sentido para o pacote principalvue— eles não incluem o compilador e têm tamanho menor.

Seleção de formato: três níveis de prioridade

📎 rollup.config.js:91-92

A seleção de formato segue três níveis de prioridade: linha de comandoFORMATSvariável de ambiente > do pacotebuildOptions.formats> padrão['esm-bundler', 'cjs']。PROD_ONLYA variável de ambiente controla se a configuração base é ignorada — se apenas a versão de produção for construída, o array de configuração base fica vazio e, em seguida, apenas a configuração de produção é adicionada.

Lógica de adição da configuração de produção

📎 rollup.config.js:97-114

QuandoNODE_ENV === 'production', para cada formato:

• SepackageOptions.prod === false, pula (o pacote não precisa de versão de produção).
• Se forcjs, adicionacreateProductionConfig— gera o arquivo.prod.js.
• Se corresponder a/^(global|esm-browser)(-runtime)?/, adicionacreateMinifiedConfig— gera a versão minificada.

createConfig: o núcleo da geração de configuração

createConfigé a maior função; ela recebe formato e configuração de saída e retorna o objeto completo de configuração Rollup.

📎 rollup.config.js:125-142

No início há uma série de cálculos de flags booleanas:

• isProductionBuild: determinado via__DEV__variável de ambiente ou se o nome do arquivo contém.prod.js.
• isBundlerESMBuild、isBrowserESMBuild、isCJSBuild、isGlobalBuild: correspondência por regex no nome do formato.
• isServerRenderer: se o nome do pacote éserver-renderer。
• isCompatPackage、isCompatBuild: relacionado à construção compatível com Vue 2.
• isBrowserBuild: construção global ou construção ESM para navegador, e sem habilitar o ramo não-navegador.

Essas flags são usadas repetidamente noresolveDefine、resolveReplace、resolveExternalsubsequente e são a base central para a diferenciação das configurações.

📎 rollup.config.js:144-157

Configurações básicas de saída: cabeçalho de copyright no banner, modoexports(pacotes compat usamauto, os demais usamnamed), construção CJS habilita interoperabilidadeesModule, sourcemap controlado por variável de ambiente,externalLiveBindings: falseereexportProtoFromExternal: falsesão configurações de compatibilidade do Rollup 4. A construção global define adicionalmenteoutput.name, ou seja, o nome da variável montada emwindow.

Seleção do arquivo de entrada

📎 rollup.config.js:159-168

A entrada padrão ésrc/index.ts, mas formatos com sufixoruntimeusamsrc/runtime.ts。A build ESM do pacote compat precisa exportar tanto default quanto named, então usa uma entradaesm-index.ts / esm-runtime.tsseparada.

Definições de macro:resolveDefine

📎 rollup.config.js:170-218

resolveDefineRetorna uma tabela de substituição, substituindo no código-fonte__COMMIT__、__VERSION__、__BROWSER__e outras macros por literais. Essas macros são usadas no código-fonte para compilação condicional — por exemploif (__DEV__) { ... }em builds de produção é substituído porif (false) { ... }, e então removido pelo Tree-shaking.

Design principal:__FEATURE_OPTIONS_API__、__FEATURE_PROD_DEVTOOLS__e outros feature flags são mantidos em buildsesm-bundlercomo identificadores__VUE_OPTIONS_API__, permitindo que usuários finais os sobrescrevam via configuração do bundler; enquanto em outros builds são codificados diretamente comotrueoufalse。

📎 rollup.config.js:203-206

builds nãoesm-bundlercodificam diretamente__DEV__, porque seus ramos dev/prod já são determinados em tempo de build.

📎 rollup.config.js:210-216

A última etapa permite que variáveis de ambiente sobrescrevam qualquer definição de macro, suportando__RUNTIME_COMPILE__=true pnpm build runtime-coresobrescritas inline como essa.

Plugin de substituição:resolveReplace

📎 rollup.config.js:222-255

resolveReplaceProcessa fora doresolveDefinesubstituições que o esbuild não consegue processar:

• MesclaenumDefines(definições de inline de enum provenientes deinlineEnums).
• Em builds de produção para navegador, adiciona anotação/*@__PURE__*/às funções de criação de erro, auxiliando o Tree-shaking.
• esm-bundlerEm builds__DEV__, substitui!!(process.env.NODE_ENV !== 'production')por
• , deixando o bundler decidir.process.envEm builds ESM para navegador, substitui

por um objeto vazio, evitando erros no navegador.resolveExternal

📎 rollup.config.js:257-283

Dependências externas:treeShakenDepsEste é o núcleo da questão de reflexão no final do capítulo anterior. O build para navegador retorna apenasdependenciescomo external — essas dependências, embora importadas, não serão realmente executadas no ramo do navegador; são listadas aqui apenas para suprimir avisos do Rollup. Os builds Node/ESM-bundler externalizam todospeerDependenciesepath、url、stream, bem como módulos internos do Node como

.

📎 rollup.config.js:319-352

Objeto de configuração final

• inputO objeto de configuração retornado contém:
• external: caminho absoluto do arquivo de entrada.
• plugins: lista de dependências externas.
• output: array de plugins, na ordem json → alias → enumPlugin → replace → esbuild → nodePlugins.
• onwarn: configuração de saída.CIRCULAR_DEPENDENCY: filtra avisos
• treeshake.moduleSideEffects: false(existem dependências circulares no código-fonte do Vue, mas são inofensivas em tempo de execução).

: informa ao Rollup que todos os módulos não têm efeitos colaterais, Tree-shaking agressivo.

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 产物落盘"]

Copiar

execGravação de artefatos em disco e verificação de tamanho

build.jsGerenciamento de processos deexecInicia o subprocesso do Rollup através de

📎 scripts/utils.js:64-114

exec:spawnencapsula

• stdio, retornando uma Promise. Design principal:['ignore', 'pipe', 'pipe']o padrão é
• shell: process.platform === 'win32'— stdin ignorado, stdout/stderr capturados por pipe.
• — no Windows é necessário shell para analisar corretamente o comando.stderrChunksColeta a saída através dos arraysstdoutChunkseexit, concatenando no evento
• .

, o que sobrescreve a configuração padrão de pipe, fazendo a saída do Rollup ser transmitida diretamente ao terminal. Este é o comportamento correto de uma ferramenta de build — o usuário precisa ver o progresso do build em tempo real.checkAllSizes

📎 scripts/build.js:206-215

Verificação de tamanho:devOnlyA verificação de tamanho tem duas condições de skip:globalé verdadeiro, ou um formato foi especificado mas não contém

📎 scripts/build.js:222-228

checkSize. Porque a verificação de tamanho é apenas para artefatos de build global — esses são os arquivos que o usuário final importa diretamente, e o tamanho é mais sensível.${target}.global.prod.jsVerifica dois arquivos:${target}.runtime.global.prod.jseglobal-runtime(o último só é verificado quando nenhum formato é especificado ou

📎 scripts/build.js:235-264

checkFileSizeé especificado).gzipSyncLê o arquivo, calcula o tamanho comprimido combrotliCompressSynceprettyBytes, formata a saída comwriteSize. Setemp/size/${fileName}.jsonfor verdadeiro, grava o resultado em

— esta é a fonte de dados para a verificação de orçamento de tamanho no CI.

📎 scripts/build.js:94-108

Construção de declarações de tipobuildTypesSepnpm run build-dtsfor verdadeiro, chama--environment TARGETS:..., passando a lista de alvos através de

. Isso garante que declarações de tipo sejam geradas apenas para os pacotes realmente construídos.

Reflexões de design e armadilhas em produção--environmentPor que usarem vez de passar parâmetros diretamente?--environmentOprocess.envdo Rollup é a única forma de passar parâmetros que pode ser lida no arquivo de configuração através de--config. Passar diretamente o parâmetroprocess.argvrequer analisar--environment, enquanto

fuzzyMatchTargetfornece análise estruturada de pares chave-valor. target.match(partialTarget)A armadilha de regex empartialTarget.runtime-core，-Emruntime.core，., o

é entrada do usuário. Se o usuário inserir runParallel, é literal na regex, sem problema; mas se inserircpus().length, corresponderá a qualquer caractere, podendo corresponder a alvos inesperados. Este é o risco inerente da correspondência difusa, mas os nomes de pacotes do Vue não contêm caracteres especiais de regex, então na prática não é acionado.--max-old-space-sizeCompetição de recursos em builds concorrentes.

scanEnumsUsa removeCachecomo limite de concorrência, mas cada processo Rollup em si também inicia workers. Em contêineres de CI com poucos núcleos, isso pode causar estouro de memória. Em produção, se ocorrer OOM, pode ser mitigado através definallyou reduzindo a concorrência.scanEnumsCiclo de vida do cache deremoveCache.finallyÉ chamado emscanEnums, mas setryem si lançar erro,

resolveExternalnão será atribuído, e a chamada emfalhará. Na prática, a função retornada porruntime-corejá está determinada antes deresolveExternal, então esse risco não existe — mas este é um detalhe de temporização que precisa ser confirmado durante a leitura.

Risco de omissão em

.node scripts/build.js vueA questão de reflexão do capítulo anterior já apontou: se adicionar uma nova dependência a

1. parseArgsmas esquecer de atualizarcommit, o build para navegador incluirá essa dependência no bundle (porque não está na lista external), causando aumento de tamanho. Este é o custo inerente da estratégia de "whitelist external".

2. run()Resumo do capítuloscanEnumsA jornada completa de umfuzzyMatchTarget:allTargets）。

3. buildAllanalisa a linha de comando,runParallelobtido sincronamente.build。

4. buildChamapackage.jsonpara gerar o cache de enum, analisa os alvos (distou--environmentatravés deexecIniciar o Rollup.

5. rollup.config.jsLer as variáveis de ambiente, através decreateConfigGerar o array de configuração,resolveDefine/resolveReplace/resolveExternalProcessar separadamente macros, substituições e dependências externas.

6. O Rollup executa a build, os artefatos são gravados em disco emdist/。

7. checkAllSizesCalcular o tamanho gzip/brotli, opcionalmente escrever emtemp/size/。

8. Se--withTypes, chamarbuild-dtsGerar as declarações de tipo.

Reflexões e autoavaliação deste capítulo

Mas o problema é: o Rollup precisa resolver os módulos antes do Tree-shaking. Se essas dependências não estiverem instaladas (por exemplo, em um ambiente CI enxuto), o Rollup reportaria um erro de "não foi possível resolver o módulo". Listá-las como external é uma medida defensiva — mesmo que as dependências não existam, o Rollup não tentará resolvê-las, apenas emitirá um aviso (escripts/dev.jsfiltraria avisos de dependências não circulares).

Progresso do livro: Capítulo 3 / 14scripts/dev.jsStatus de verificação: Linhas FACT com ancoragem realscripts/pre-dev-sfc.jsNo capítulo anterior, rastreamos a cadeia completa da build de produção, desde a análise de parâmetros até a gravação de artefatos em múltiplos formatos, uma cadeia que busca a completude e padronização dos artefatos. Já a demanda central do fluxo de desenvolvimento é apenas uma: alterar uma linha de código e ver o efeito imediatamente no navegador. A cadeia da build de produção — "analisar parâmetros → gerar configuração → empacotar tudo → gravar em disco" — leva dezenas de segundos, incapaz de atender a essa demanda. O repositório do Vue core mantém, para isso, uma cadeia independente de desenvolvimento:

usar o modo watch do esbuild para build incremental,

pré-compilar o compilador de SFC antes da build principal. Este capítulo disseca o mecanismo de colaboração entre os dois.

3.1 dev.js: o construtor incremental que troca velocidade pelo esbuild📎 scripts/dev.js:3-5

Modelo intuitivo

A build de produção é como "a gráfica fazendo a composição formal para impressão" — qualidade em primeiro lugar, ser mais lento não importa; a build de desenvolvimento é como "um esboço a lápis no rascunho" — sem buscar refinamento, apenas que apareça assim que a caneta tocar o papel. O Vue escolhe o esbuild em vez do Rollup para fazer esse esboço, e o motivo está escrito no comentário no início do arquivo: os artefatos do Rollup são menores e o Tree-shaking é melhor, mas o esbuild é muito mais rápido.

Sem este script, o desenvolvedor teria que rodar uma build de produção completa a cada alteração, e o ciclo de feedback degradaria de milissegundos para minutos, destruindo completamente a experiência de hot update.parseArgsAnálise de parâmetros e derivação de formatoformatA entrada do script usa oglobal）、prodnativo do Node para analisar três opções:false）、inline(padrãofalse）。📎 scripts/dev.js:18-40parâmetros posicionais são coletados comotargets, se vazio então o padrão é['vue']。📎 scripts/dev.js:42-53

formatO mapeamento para o formato de saída do esbuild tem três ramos: começando comglobalmapeia paraiife, igual acjsmapeia paracjs, todo o restoesm。📎 scripts/dev.js:42-53O sufixo do nome do arquivo de saída é tratado separadamente pelo sufixo-runtime:global-runtimese tornaruntime.global, o restante permanece como está.📎 scripts/dev.js:42-53

Localização do pacote alvo e caminho de saída

O script primeiro lêpackages-privatea lista de diretórios, para determinar se o pacote alvo pertence a pacote público ou privado.📎 scripts/dev.js:56Para cada target, decide se o caminho base do pacote épackagesoupackages-private, depoisrequireseupackage.jsonpara obterversionebuildOptions。📎 scripts/dev.js:58-63

O nome do arquivo de saída tem um caso especial:vue-compato target será renomeado paravue, para evitar que o artefato se chamevue-compat.global.js。📎 scripts/dev.js:64-69O caminho final tem a formapackages/vue/dist/vue.global.js，prodquando verdadeiro, insereprod.o segmento.

Resolução de external: evitar empacotar dependências no artefato

externalO array determina quais módulos não serão empacotados. A lógica é dividida em duas camadas:

Primeira camada, quandoinlinenão está ativado e o formato écjsou contémesm-bundler, adiciona todas as chaves dedependencies、peerDependenciesao external, e codifica fixamentepath、url、streamtrês módulos internos do Node.📎 scripts/dev.js:76-88O comentário explica claramente que esses três são para@vue/compiler-sfceserver-renderer.

Segunda camada, para o targetcompiler-sfc, resolve adicionalmente@vue/consolidateodevDependenciesdefs、vm、crypto, colocando-os junto com📎 scripts/dev.js:90-112etc. como external.react-dom/server、teacup/lib/express、arc-templates/dist/es5、then-pug、then-jadeO código também codifica fixamente caminhos de template engines como

). A razão de não extrair uma função comum é que as estratégias de external de dev e prod têm diferenças sutis (dev é mais agressivo em externalizar para acelerar o build), forçar a unificação aumentaria o acoplamento.

Plugins e injeção de definelog-rebuildO array de plugins tem por padrão apenas umonEnd, no hook📎 scripts/dev.js:115-124imprime o caminho relativo do artefato de build.

define) ainda seguem o ramo Node em builds de navegador, precisam de polyfill de módulos internos do Node para rodar no ambiente de navegador.📎 scripts/dev.js:141-159O bloco é a parte de maior densidade de informação deste capítulo.__XXX__Ele substitui todas as macros

• __COMMIT__no código-fonte por literais:"dev"，__VERSION__fixado como
• __DEV__pega a versão do pacote;proddeterminado pela flag__TEST__,false；
• __BROWSER__sempre éformat !== 'cjs' && !pkg.buildOptions?.enableNonBrowserBranches。📎 scripts/dev.js:146-148A derivação de é a mais sutil:
• __SSR__Ou seja, apenas "não cjs e o pacote não suporta ramo não-navegador" é marcado como ambiente de navegador;format !== 'global'é
• __COMPAT__, ou seja, builds global não ativam o ramo SSR;vue-compatdeterminado por se o target é
• ;__FEATURE_SUSPENSE__、__FEATURE_OPTIONS_API__、__FEATURE_PROD_DEVTOOLS__、__FEATURE_PROD_HYDRATION_MISMATCH_DETAILS__três feature flags (

) são todos fixados no modo dev.vitest.config.tsEssas macros correspondem um a um com o blocodefineem📎 vitest.config.ts:6-21.__TEST__O ambiente de teste definetrue、__DEV__comotruecomo

, a diferença com o build dev é exatamente o ponto de distinção entre os dois estados de execução "teste vs desenvolvimento".

Inicialização do modo watchesbuild.context(...).then(ctx => ctx.watch())。📎 scripts/dev.js:130-161 contextO último passo éwatch()criar o contexto de build mas não executar imediatamente,onEndsó então realmente inicia o monitoramento de arquivos. Depois disso o esbuild mantém internamente o grafo de dependências, qualquer mudança em arquivo dependido dispara rebuild incremental, o callback de conclusão do rebuild

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: 相对路径"]

Copiar

3.2 pre-dev-sfc.js: sentinela de pré-compilação para quebrar dependência circular

Modelo intuitivocompiler-sfcImagine um dilema "ovo e galinha":compiler-coreo código-fonte de importacompiler-core, ecompiler-sfcem modo de desenvolvimento precisa de.vuepara processar arquivospre-dev-sfc.js. Se ambos dependem de compilação em tempo real via esbuild watch, quem compilar primeiro trava.

O papel de é "chocar o ovo primeiro, depois criar a galinha" — antes do build principal iniciar, garantir que os artefatos CJS desses pacotes já existam.

Checklist e lógica de curto-circuitocompiler-sfc、compiler-core、compiler-dom、compiler-ssr、shared。📎 scripts/pre-dev-sfc.js:4-10O script mantém uma lista fixa:packages/${pkg}/dist/${pkg}.cjs.jsPara cada pacote, verifica se📎 scripts/pre-dev-sfc.js:4-23

existe.allFilesPresentSe qualquer um estiver faltando,falsedefine comobreake imediatamente📎 scripts/pre-dev-sfc.js:20-21, não verifica os pacotes restantes.allFilesPresentFinalmente, seprocess.exit(1)for falso,📎 scripts/pre-dev-sfc.js:25-27

sai com código diferente de zero.

Semântica do código de saídaexit(1)Este script em si não executa nenhuma compilação, ele apenas faz "asserção de existência".&&É o sinal para o chamador superior (geralmente a cadeia

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"]

Copiar

scripts/dev.js3.3 aliases.js e vitest.config.ts: a outra metade do fluxo em desenvolvimentoscripts/aliases.jsresolve "como gerar artefatos rapidamente", mas em desenvolvimento há outro caminho: rodar testes.📎 scripts/aliases.js:7-7

fornece aliases de caminho compartilhados para vitest e rollup.

resolveEntryForPkgLógica de geração de aliasespackages/${p}/src/index.ts。📎 scripts/aliases.js:7-7mapeia nomes de pacotes paravue、vue/compiler-sfc、vue/server-renderer、@vue/compat。📎 scripts/aliases.js:16-21

entries base codifica fixamente quatro mapeamentos especiais:packagesEm seguida percorre todos os subdiretórios sobvue, pulanonSrcPackages（sfc-playground、template-explorer、dts-testem si, pula@vue/${dir}), pula keys já existentes, e deve ser diretório, só então adiciona ao mapeamento📎 scripts/aliases.js:23-35

O define do vitest e o consumo de aliases

vitest.config.tsimportar diretamenteentriescomoresolve.alias。📎 vitest.config.ts:3📎 vitest.config.ts:22-24o seudefinebloco contrasta com a injeção de macros do dev.js: ambiente de teste__DEV__: true、__TEST__: true、__BROWSER__: false、__CJS__: true。📎 vitest.config.ts:6-21

Os testes são divididos em cinco projetos:unit、unit-gc、unit-jsdom、e2e、e2e-browser。📎 vitest.config.ts:51-118entre os quaisunit-gcusapool: 'forks'e passa--expose-gc, dedicado a executar testes SSR que requerem acionamento manual do GC.📎 vitest.config.ts:65-76 e2e-browserPor sua vez, ativa a instância chromium do playwright, executando testes relacionados com Transition.📎 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

Reflexão de design

Porque é que o dev usa esbuild e o prod usa Rollup?Isto não é uma escolha técnica arbitrária, mas sim porque as restrições dos dois cenários são diferentes. Em desenvolvimento, o tamanho do artefacto não é sensível, mas a latência de feedback é extremamente sensível; em produção, o inverso. O esbuild é escrito em Go, com alto grau de paralelização, arranque a frio e construção incremental uma ordem de magnitude mais rápidos, mas a sua capacidade de Tree-shaking e divisão de código é inferior à do Rollup.📎 scripts/dev.js:3-5Usar dois conjuntos de ferramentas para servir dois cenários é um compromisso pragmático de engenharia.

A duplicação da lista external é dívida técnica?A lógica external do dev.js e do rollup.config.js está duplicada, e os comentários no código-fonte também o admitem.📎 scripts/dev.js:73Mas os conjuntos external de ambos não são completamente idênticos — o dev, por questões de velocidade, externaliza de forma mais agressiva. Extrair forçadamente uma função comum exigiria introduzir interruptores de diferença parametrizados, tornando ambas as lógicas mais difíceis de ler. Este é um exemplo típico do compromisso "duplicação é melhor que abstração errada".

Resumo do capítulo

Este capítulo desmontou as três peças do puzzle da cadeia de desenvolvimento do Vue core:

1. scripts/dev.js: usar ocontext().watch()do esbuild para implementar construção incremental, através doparseArgsanalisar formato e flags, dinamicamenterequireo pacote alvopackage.jsonlocalizar o caminho de saída, injetar__DEV__、__BROWSER__e outras macros para controlar compilação condicional, e usar olog-rebuildplugin para imprimir feedback após cada reconstrução.

2. scripts/pre-dev-sfc.js: antes da construção principal, verificar se os artefactos CJS dos cinco pacotes principais existem; se faltarem, terminar com código de saída 1, evitando deadlock de construção causado por dependências circulares.

3. scripts/aliases.js + vitest.config.ts: fornecer aliases de caminho partilhados para a cadeia de testes, itens especiais codificados manualmente mais itens genéricos com varrimento dinâmico, em conjunto com configuração multi-projeto cobrindo cinco cenários de teste: unitário, GC, jsdom, e2e e e2e de browser.

Reflexão e autoavaliação do capítulo

A fronteira da colaboração entre os três é bem clara:pre-dev-sfcgerencia "se o artefato está pronto",dev.jsgerencia "como atualizar o artefato rapidamente",aliasesgerencia "como os testes resolvem o código-fonte". A cadeia em tempo de desenvolvimento resolve o problema de velocidade, mas na fase de build há outro tipo de otimização mais oculta — aquelas transformações concluídas antes de o código ser executado pelo navegador. O próximo capítulo entrará na magia do tempo de compilação, para ver como o inline de enums e o mecanismo de verificação de Tree-shaking substituem TypeScript enum por literais durante o build e garantem que a promessa de importação sob demanda não seja quebrada.

No capítulo anterior vimos como a cadeia em tempo de desenvolvimento troca observação de arquivos e build incremental pela velocidade de "alterar uma linha e entrar em vigor imediatamente". Mas além da velocidade, Vue tem outra restrição mais oculta: o tamanho do artefato publicado deve ser controlável. Um dos inimigos dessa restrição é o enum do TypeScript — ele é um objeto real em tempo de execução e quebra o Tree-shaking. Este capítulo entra no tempo de compilação para ver como scripts/inline-enums.js "dissolve" enums em literais antes de o código ser executado pelo navegador; e depois ver como scripts/verify-treeshaking.js, após o build, usa strings do artefato para verificar reversamente que a promessa de "importação sob demanda" não foi silenciosamente quebrada.

4.1 Inline de enums: dissolvendo objetos de tempo de execução em literais

Modelo intuitivo

Imagine que você escreveu uma receita na qual "um pouco de sal" aparece repetidamente. Se toda vez que cozinhasse fosse preciso ir ao apêndice consultar "um pouco = 3 gramas", seria lento e ocuparia espaço. O que o inline de enums faz é, antes da impressão, substituir diretamente todo "um pouco de sal" do livro por "3 gramas de sal" e depois rasgar aquela página do apêndice. Para o leitor (tempo de execução), o resultado é exatamente o mesmo, mas o livro fica mais fino.

Sem isso, que desastre o sistema enfrentaria? Umenumcomum do TypeScript, após compilação, gera um objeto literal real e com mapeamento bidirecional (Enum[Enum.A] === 'A'). Esse objeto éuma declaração em nível de módulo com efeitos colaterais, e o Rollup não consegue provar que ele não é usado, então só pode mantê-lo — mesmo que você importe apenas um de seus membros, todo o objeto enum junto com o mapeamento reverso será incluído no artefato.📎 scripts/inline-enums.js:3-9O comentário deconst enumdiz claramente: eles já usaram

, mas por causa da issue #1228 mudaram para enum comum, então usam este script para "recuperar manualmente o benefício de custo zero do const enum".

Estrutura de dados e layout de memória📎 scripts/inline-enums.js:33-36

• EnumMember：{ name, value }O núcleo do script são três definições de tipo; entendê-las é entender todo o fluxo de dados.
• EnumDeclaration：{ id, range: [start, end], members }。range, o nome de um único membro de enum e o literal após avaliação.éo deslocamento em bytes do código-fonteexport enum X { ... }, apontando para a posição inicial e final de toda a declaração
• EnumData：{ declarations, defines }。declarationsno arquivo — esta é a âncora para a substituição precisa posterior com MagicString.definesindexado por caminho de arquivo, registrando os intervalos de substituição de todas as declarações de enum nesse arquivo; é um mapeamento plano, cuja chave é o literal após ` 形式的字符串，值是 ${nomeDoEnum}.${nomeDoMembro}

JSON.stringify`.definesHá um design-chave aqui:a chave de。📎 scripts/inline-enums.js:98-103não contém caminho de arquivoErrorCodesO comentário explica o motivo —@vue/compiler-corepode existir simultaneamente em@vue/runtime-coreeErrorCodes.__EXTEND_POINT__, então enums com o mesmo nome podem existir em arquivos diferentes; mas o mesmofullKey in definesnão pode se repetir em dois enums com o mesmo nome, caso contrárioname conflicté acionado e lança

diretamente. Esta é uma restrição de "unicidade global por nome de membro", não de "unicidade global por nome de enum".temp/enum.json。📎 scripts/inline-enums.js:33-36O cache fica emscanEnums()Por que precisa ser gravado em disco? Porqueé chamado apenas uma vez na entrada do build, e o Rollup iniciará。📎 scripts/inline-enums.js:39-41processos independentesinlineEnums()para cada pacote e cada formato. O comentário aponta: os dados precisam ser compartilhados entre processos concorrentes do Rollup, então devem ser serializados em disco e lidos de volta pelo

de cada processo.

Step-by-Step: de grep à substituição por literaisexport enumPrimeiro passo: grep de todos os arquivos contendo📎 scripts/inline-enums.js:51-61.spawnSync('git', ['grep', 'export enum'])usapath:line:content, com saída no formato:, depois corta o primeiro segmento porSet(caminho do arquivo), e usagit grepem vez de percorrer o sistema de arquivos — ele naturalmente varre apenas os arquivos rastreados pelo Git, excluindo automaticamentenode_modulese artefatos de build.

Segundo passo: o Babel analisa e coleta informações de enum.📎 scripts/inline-enums.js:64-70Para cada arquivo usa@babel/parsercomtypescriptplugin,sourceType: 'module'analisa em AST, e então percorre apenasast.program.bodyos nós de nível superior.📎 scripts/inline-enums.js:74-79Reconhece apenasExportNamedDeclaratione cujodeclaration.type === 'TSEnumDeclaration'nó — ou seja,enums não exportados não serão processados。

Para cada declaração de enum, o script avalia membro por membro. A avaliação de membros segue três caminhos:

1. Inicialização literal：StringLiteralouNumericLiteralobtém diretamenteinit.value。📎 scripts/inline-enums.js:114-119

2. Expressão binária: como1 << 2. RecursivamenteresolveValueprocessa os operandos esquerdo e direito, os operandos podem ser literais ouMemberExpression(ou seja, referência a um membro de enum já definido anteriormente).📎 scripts/inline-enums.js:121-151O ponto-chave está noMemberExpressionbranch: ele usacontent.slice(node.start, node.end)a partir dotexto do código-fonte originalpara extrair a string da expressão (comoErrorCodes.FOO), depois consultadefines. Se não encontrar, lançaunhandled enum initialization expression。📎 scripts/inline-enums.js:132-141Isso explica por quedefinesdeve ser um mapeamento global plano — ao referenciar entre enums, o referenciado pode vir de outro arquivo, mas a chave reconhece apenas枚举名.成员名。

3. Expressão unária: como-1, monta a string-1e usaevaluatepara avaliar.📎 scripts/inline-enums.js:152-163

A avaliação em si usanew Function('return ' + exp)()。📎 scripts/inline-enums.js:39-41Este é umeval controlado: a entrada vem de fragmentos de AST já analisados no código-fonte, não de entrada arbitrária do usuário, então o limite de segurança é controlável.

Terceiro passo: processar membros sem inicializador (semântica de auto-incremento).📎 scripts/inline-enums.js:171-183Se o membro não teminitializer: o primeiro membro por padrão0; membros subsequentes, selastInitializedfor numérico então++; se for string, lançawrong enum initialization sequence— porque membros de enum string não permitem auto-incremento implícito. Esta é exatamente a semântica do enum do TypeScript.

Quarto passo: gravar cache e retornar função de limpeza.📎 scripts/inline-enums.js:200-213 scanEnums()Retorna um closure, cuja chamadarmSyncexclui o arquivo de cache.build.jsUsa-o emtry/finally.📎 scripts/build.js:81-112Isso garante que mesmo se um erro for lançado no meio do build, o cache será limpo, não contaminando o próximo build.

Quinto passo: substituição na fase de transform do Rollup. inlineEnums()Lê de volta o cache, constrói um plugin Rollup.📎 scripts/inline-enums.js:219-234Emtransform(code, id), seidcorresponder aenumData.declarations, usa MagicString para substituir[start, end]este trecho de declaração por um object literal.📎 scripts/inline-enums.js:242-274

A forma após a substituição éexport const X = { ... }. Note que elenão simplesmente remove o enum, mas reescreve como object literal, e gera mapeamento reverso adicional para membros numéricos:JSON.stringify(value.toString()) + ': ' + JSON.stringify(name)。📎 scripts/inline-enums.js:257-270O comentário cita a regra de reverse-mappings da documentação oficial do TypeScript: membros de enum string não geram mapeamento reverso, membros numéricos geram. Isso garante que o comportamento em tempo de execução após a substituição seja completamente idêntico ao enum original.

E o que realmente elimina a sobrecarga em tempo de execução édefinesser entregue a@rollup/plugin-replace。📎 rollup.config.js:222-223Todas asX.Memberreferências asãono plugin de substituição diretamente trocadas por literais, então aquele object literal reescrito, se ninguém o usar, pode ser eliminado pelo Tree-shaking.

O fluxograma abaixo descreve o caminho completo de decisão do grep até a substituição:

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 替换引用"]

Reflexões de design e armadilhas

Por que usar MagicString em vez de regenerar o arquivo inteiro?Porques.update(start, end, ...)substitui apenas o trecho da declaração do enum, os demais bytes do código-fonte permanecem intactos,s.generateMap()e ainda gera sourcemap preciso.📎 scripts/inline-enums.js:277-281Se usasse Babel para reimprimir todo o AST, perderia a formatação original, comentários, e a qualidade do sourcemap diminuiria.

rangePor quenode.start/node.endem vez dedeclaration.start？📎 scripts/inline-enums.js:189-193afirmanode.start(ou seja,ExportNamedDeclarationnó), o escopo de substituição cobreexport enum X {...}todo o trecho, incluindoexporta palavra-chave. O texto de substituição começa comexport const, conectando-se perfeitamente.

Armadilhas:definesA restrição de unicidade global deSe dois arquivos diferentes tiverem cada um umErrorCodes, e ambos definirem__EXTEND_POINT__, o build falhará diretamente.📎 scripts/inline-enums.js:101-103Isso não é um bug, mas um design intencional — porquedefinesé uma tabela de substituição global, incapaz de distinguir a origem do arquivo. Em ambiente de produção, ao adicionar novos membros de enum, se o nome conflitar com um membro de enum existente, explodirá aqui.

Armadilha:new FunctionO momento de avaliação deA avaliação de expressão binária ocorre nascanEnumsfase, neste momentodefinespode ainda não ter o membro referenciado (se a ordem de referência estiver invertida).📎 scripts/inline-enums.js:136-140lançaráunhandled enum initialization expression. Isso exige que a referência a membros de enum siga a ordem do código-fonte de "definir antes de referenciar".

4.2 Verificação de Tree-shaking: usar strings do artefato para provar a promessa inversamente

Modelo intuitivo

O inline de enum é uma "otimização prévia", mas a otimização realmente funciona? Se algum helper for mantido acidentalmente por escrita inadequada, o tamanho inflará silenciosamente, e o desenvolvedor nem perceberá.verify-treeshaking.jsÉ o "inspetor de qualidade posterior": ele constrói o artefato, e então como uma autópsia verifica no artefatose coisas que não deveriam aparecer aparecem. Sem ele, a promessa de importação sob demanda do Vue pode silenciosamente quebrar após alguma refatoração, até que usuários reclamem que o pacote cresceu.

Estrutura de dados e itens de verificação

Este script não tem estrutura de dados complexa, o núcleo é umerrorsarray e trêsincludesverificações.📎 scripts/verify-treeshaking.js:6-6Ele primeiro constróiglobal-runtimeformato, depois lê separadamente os artefatos dev e prod.

Os três itens de verificação correspondem a três tipos de "falha de Tree-shaking":

1. artefato dev contém__spreadValues。📎 scripts/verify-treeshaking.js:13-19Este é o helper gerado pelo esbuild para{ ...obj }sintaxe de spread de objeto. Se ele aparecer, significa que o código em tempo de execução usou spread de objeto, enquanto a convenção do Vue deveria usarextendhelper para evitar código extra.

2. artefato prod contémVue warn。📎 scripts/verify-treeshaking.js:26-31significa que háwarn()chamada não envolvida por__DEV__condição, causando vazamento de código de aviso no pacote de produção.

3. artefato prod contém lista de configuração de DOM tag。📎 scripts/verify-treeshaking.js:33-42comohtml,body,base、svg,animate,animateMotion、annotation,annotation-xml,maction. Estes sãoisHTMLTag()Os dados internos de helpers como este deveriam existir apenas no compilador e ser eliminados pelo runtime. Se aparecerem no artefato de runtime, isso indica que o caminho de runtime usou erroneamente um helper exclusivo do compilador.

Passo a passo: fluxo de verificação

📎 scripts/verify-treeshaking.js:5-5Primeiroexec('pnpm', ['build', 'vue', '-f', 'global-runtime']), construir apenasvueo pacoteglobal-runtimeno formato — este é o artefato de runtime mais minimizado, ideal para expor vazamentos. Após a construção, ler os dois arquivos de forma síncrona, verificarincludesum por um, e ao encontrar correspondência, fazer push de uma mensagem com explicação emerrors. Por fim, seerrors.lengthfor diferente de zero, lançar um erro agregado.📎 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 聚合错误"]

Reflexões de design e armadilhas

4.3 Colaboração com Rollup: ordem de plugins e injeção de define

O inlining de enums não opera isoladamente; ele está embutido no pipeline de plugins do Rollup. Entender sua posição no pipeline é essencial para compreender por quedefinesdeve ser entregue areplaceem vez deesbuild。

📎 rollup.config.js:47-50chamar no nível superior do módulo de configuraçãoinlineEnums(), desestruturando[enumPlugin, enumDefines]. Note que isto é executadoa cada inicialização de processo do Rollup, lendo o cache escrito porscanEnums.

A ordem do array de plugins é:json → alias → enumPlugin → ...resolveReplace() → esbuild。📎 rollup.config.js:324-339 enumPluginvem antes dereplace, significando que a reescrita das declarações de enum ocorre primeiro, e entãoreplaceusadefinespara substituir referências. Eesbuildvem por último, responsável pela transpilação TS.

Por quedefinesusareplacee nãoesbuild? O comentário emdefine？📎 rollup.config.js:220-221dá a resposta: o define do esbuild "é um pouco estrito, permitindo apenas JSON literal ou identificadores". E nomes de membros de enum comoErrorCodes.__EXTEND_POINT__são expressões de membro com ponto, e o define do esbuild não consegue lidar diretamente com tais chaves. Portanto, é obrigatório usar@rollup/plugin-replace, que suporta substituição de chaves de string arbitrárias.📎 rollup.config.js:250-251E configuroupreventAssignment: true, evitando substituir também o lado esquerdo de instruções de atribuição.

resolveReplace()Emconst replacements = { ...enumDefines }é o primeiro passo.📎 rollup.config.js:222-223Somente depois é que se sobrepõem as anotações de produção/*@__PURE__*/,__DEV__e outras substituições. Esta ordem garante que a substituição de literais de enum sempre tenha efeito.

Reflexões de design

A essência do inlining de enums é "trocar complexidade em tempo de build por tamanho em tempo de runtime".Ele reproduz completamente em tempo de build a semântica do sistema de tipos do TypeScript (avaliação de enum, auto-incremento, mapeamento reverso) —scanEnumsa lógica de avaliação em📎 scripts/inline-enums.js:110-183é quase um subconjunto da avaliação de enum do compilador TS. Isso traz custo de manutenção: se o TS adicionar nova sintaxe de enum (como expressões constantes mais complexas), aqui deve-se acompanhar, caso contrário lança errounhandled. Mas o benefício é claro: zero objetos de enum em runtime, permitindo Tree-shaking completo.

Cache entre processos é essencial para builds concorrentes. scanEnumsO padrão de execução única,inlineEnumsmúltiplas leituras,📎 scripts/inline-enums.js:39-41resolve o problema de "uma varredura, N processos consumindo". Sem cache, cada processo Rollup teria que refazer grep + parsing, desperdiçando muito IO e CPU.

Resumo do capítulo

Reflexões e autoavaliação do capítulo

枚举内联解决了「构建期如何消除运行时开销」，验证脚本解决了「如何确认优化没被破坏」。但构建产物除了 JS，还有一类同样需要流水线加工的产物——类型声明文件。下一章将进入类型产物流水线，看 Vue 如何从源码.d.ts生成发布级类型包，以及dts-test如何用类型契约测试守住公开 API 的类型形状。

本章拆解了编译期的两个关键脚本。inline-enums.js 用 git grep 定位枚举、Babel 解析 AST、new Function 求值成员、MagicString 精确重写声明，最终通过 defines 全局替换表把枚举引用变成字面量，让枚举对象可被 Tree-shaking 摇掉。verify-treeshaking.js 则在构建后用字符串哨兵检查产物，确保三类已知的 Tree-shaking 泄漏不会回归。两者一个负责「优化」，一个负责「验证优化没被破坏」，共同守护 Vue 的体积承诺。接下来，我们将从编译期转向类型产物的生成链路，看 Vue 如何保证源码类型与发布类型严格一致。