Back to Details

reference-compiler-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Angular Compiler CLI (
ngtsc
) Architecture

Angular Compiler CLI（
ngtsc
）架构

Overview

概述

The 
packages/compiler-cli
package contains the Angular Compiler (Ivy), often referred to as 
ngtsc
. It is a wrapper around the TypeScript compiler (
tsc
) that extends it with Angular-specific capabilities.
The core goal of 
ngtsc
is to compile Angular decorators (like 
@Component
, 
@Directive
, 
@Pipe
) into static properties on the class (Ivy instructions, e.g., 
static ɵcmp = ...
). It also performs template type checking and ahead-of-time (AOT) compilation.
packages/compiler-cli
包包含Angular编译器（Ivy），通常被称为
ngtsc
。它是TypeScript编译器（
tsc
）的包装器，扩展了Angular专属的功能。
ngtsc
的核心目标是将Angular装饰器（如
@Component
、
@Directive
、
@Pipe
）编译为类上的静态属性（Ivy指令，例如
static ɵcmp = ...
）。它还执行模板类型检查和提前（AOT）编译。

Mental Model

思维模型

The compiler is designed as a lazy, incremental, and partial compilation pipeline.
  1. Wrapper Pattern: 
    NgtscProgram
    wraps the standard 
    ts.Program
    . It intercepts calls to act as a drop-in replacement for standard tooling.
  2. Traits System: Every class with an Angular decorator is considered a "Trait". The compiler manages the state of these traits through a state machine:
    • Pending: Detected but not processed.
    • Analyzed: Metadata extracted, template parsed (but dependencies not yet linked).
    • Resolved: Dependencies (directives/pipes in template) resolved, import cycles handled.
    • Skipped: Not an Angular class.
  3. Lazy Analysis: Analysis only happens when necessary (e.g., when diagnostics are requested or emit is prepared).
  4. Output AST: The compiler generates an intermediate "Output AST" (
    o.Expression
    ) for the generated code, which is then translated into TypeScript AST nodes during the emit phase.
该编译器被设计为惰性、增量式且部分编译的流水线。
  1. 包装器模式：
    NgtscProgram
    包装标准的
    ts.Program
    。它拦截调用，作为标准工具的直接替代方案。
  2. 特质系统：每个带有Angular装饰器的类都被视为一个“Trait”。编译器通过状态机管理这些特质的状态：
    • Pending（待处理）：已检测到但未处理。
    • Analyzed（已分析）：元数据已提取，模板已解析（但依赖尚未关联）。
    • Resolved（已解析）：依赖（模板中的指令/管道）已解析，导入循环已处理。
    • Skipped（已跳过）：非Angular类。
  3. 惰性分析：仅在必要时才进行分析（例如，当请求诊断信息或准备输出时）。
  4. 输出AST：编译器为生成的代码生成中间“输出AST”（
    o.Expression
    ），然后在输出阶段将其转换为TypeScript AST节点。

Key Subsystems

核心子系统

1. Core Orchestration (
ngtsc/core
)

1. 核心编排（
ngtsc/core
）

  • NgtscProgram
    : The public API implementing 
    api.Program
    . It manages the 
    ts.Program
    and the 
    NgCompiler
    .
  • NgCompiler
    : The brain of the compiler. It orchestrates the compilation phases (Analysis, Resolution, Type Checking, Emit). It holds the 
    TraitCompiler
    .
  • NgtscProgram
    ：实现
    api.Program
    的公开API。它管理
    ts.Program
    和
    NgCompiler
    。
  • NgCompiler
    ：编译器的核心。它编排编译阶段（分析、解析、类型检查、输出）。它持有
    TraitCompiler
    。

2. Trait Compilation (
ngtsc/transform
)

2. 特质编译（
ngtsc/transform
）

  • TraitCompiler
    : Manages the lifecycle of "Traits". It iterates over source files, identifies decorated classes, and delegates to the appropriate 
    DecoratorHandler
    .
  • Trait
    : A state container for a class, holding its handler, analysis results, and resolution results.
  • TraitCompiler
    ：管理“Trait”的生命周期。它遍历源文件，识别带有装饰器的类，并委托给相应的
    DecoratorHandler
    。
  • Trait
    ：类的状态容器，包含其处理程序、分析结果和解析结果。

3. Decorator Handlers (
ngtsc/annotations
)

3. 装饰器处理程序（
ngtsc/annotations
）

  • DecoratorHandler
    : An interface for handling specific decorators.
  • ComponentDecoratorHandler
    : The most complex handler. It:
    • Extracts metadata (selector, inputs, outputs).
    • Parses the template.
    • Resolves used directives and pipes (
      R3TargetBinder
      ).
    • Generates the 
      ɵcmp
      instruction.
  • DirectiveDecoratorHandler
    , 
    PipeDecoratorHandler
    , 
    NgModuleDecoratorHandler
    : Handle their respective decorators.
  • DecoratorHandler
    ：用于处理特定装饰器的接口。
  • ComponentDecoratorHandler
    ：最复杂的处理程序。它：
    • 提取元数据（选择器、输入、输出）。
    • 解析模板。
    • 解析使用的指令和管道（通过
      R3TargetBinder
      ）。
    • 生成
      ɵcmp
      指令。
  • DirectiveDecoratorHandler
    、
    PipeDecoratorHandler
    、
    NgModuleDecoratorHandler
    ：处理各自对应的装饰器。

4. Template Type Checking (
ngtsc/typecheck
)

4. 模板类型检查（
ngtsc/typecheck
）

  • TemplateTypeChecker
    : Generates "Type Check Blocks" (TCBs). A TCB is a block of TypeScript code that represents the template's logic in a way 
    tsc
    can understand and check for errors.
  • TypeCheckBlock
    : The actual generated code that validates bindings, events, and structural directives.
  • TemplateTypeChecker
    ：生成“类型检查块”（TCB）。TCB是一段TypeScript代码，以
    tsc
    可以理解并检查错误的方式表示模板逻辑。
  • TypeCheckBlock
    ：实际生成的代码，用于验证绑定、事件和结构指令。

5. Metadata & Scope (
ngtsc/metadata
, 
ngtsc/scope
)

5. 元数据与作用域（
ngtsc/metadata
、
ngtsc/scope
）

  • MetadataReader
    : Reads Angular metadata from source files (using 
    LocalMetadataRegistry
    ) and 
    .d.ts
    files (using 
    DtsMetadataReader
    ).
  • ScopeRegistry
    : Determines the "compilation scope" of a component (which directives/pipes are available to it), handling 
    NgModule
    transitive exports and Standalone Component imports.
  • MetadataReader
    ：从源文件（使用
    LocalMetadataRegistry
    ）和
    .d.ts
    文件（使用
    DtsMetadataReader
    ）中读取Angular元数据。
  • ScopeRegistry
    ：确定组件的“编译作用域”（哪些指令/管道可用于该组件），处理
    NgModule
    的传递导出和独立组件的导入。

6. Emit & Transformation (
ngtsc/transform
)

6. 输出与转换（
ngtsc/transform
）

  • ivyTransformFactory
    : A TypeScript transformer factory.
  • IvyCompilationVisitor
    : Visits classes, triggers compilation via 
    TraitCompiler
    , and collects the Output AST.
  • IvyTransformationVisitor
    : Translates the Output AST into TypeScript AST, injects the 
    static ɵ...
    fields, and removes the original decorators.
  • ivyTransformFactory
    ：TypeScript转换器工厂。
  • IvyCompilationVisitor
    ：遍历类，通过
    TraitCompiler
    触发编译，并收集输出AST。
  • IvyTransformationVisitor
    ：将输出AST转换为TypeScript AST，注入
    static ɵ...
    字段，并移除原始装饰器。

Compilation Phases

编译阶段

  1. Construction: 
    NgtscProgram
    creates 
    NgCompiler
    , which sets up all registries and the 
    TraitCompiler
    .
  2. Analysis (
    analyzeSync
    ):
    • The 
      TraitCompiler
      scans files.
    • DecoratorHandler
      s extract metadata and parse templates.
    • No cross-file resolution happens here (allowing for parallelism and caching).
  3. Resolution (
    resolve
    ): 
    • TraitCompiler
      resolves traits.
    • Components link their templates to specific Directives and Pipes (found via 
      ScopeRegistry
      ).
    • Import cycles are detected and handled (e.g., via "remote scoping").
  4. Type Checking: 
    • TemplateTypeChecker
      creates TCBs for all components.
    • TypeScript diagnostics are retrieved for these TCBs.
  5. Emit (
    prepareEmit
    ): 
    • ivyTransformFactory
      is created.
    • TS 
      emit
      is called.
    • The transformers run, injecting the compiled Ivy instructions into the JS/DTS output.
  1. 构建：
    NgtscProgram
    创建
    NgCompiler
    ，后者设置所有注册表和
    TraitCompiler
    。
  2. 分析（
    analyzeSync
    ）： 
    • TraitCompiler
      扫描文件。
    • DecoratorHandler
      提取元数据并解析模板。
    • 此阶段不进行跨文件解析（允许并行处理和缓存）。
  3. 解析（
    resolve
    ）： 
    • TraitCompiler
      解析特质。
    • 组件将其模板与特定的指令和管道关联（通过
      ScopeRegistry
      查找）。
    • 检测并处理导入循环（例如，通过“远程作用域”）。
  4. 类型检查： 
    • TemplateTypeChecker
      为所有组件创建TCB。
    • 从这些TCB中获取TypeScript诊断信息。
  5. 输出（
    prepareEmit
    ）：
    • 创建
      ivyTransformFactory
      。
    • 调用TS的
      emit
      方法。
    • 转换器运行，将编译后的Ivy指令注入到JS/DTS输出中。

Important File Locations

重要文件位置

  • packages/compiler-cli/src/ngtsc/program.ts
    : Entry point (
    NgtscProgram
    ).
  • packages/compiler-cli/src/ngtsc/core/src/compiler.ts
    : Core logic (
    NgCompiler
    ).
  • packages/compiler-cli/src/ngtsc/transform/src/trait.ts
    : Trait state machine.
  • packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts
    : Component compilation logic.
  • packages/compiler-cli/src/ngtsc/typecheck/src/template_type_checker.ts
    : Type checking logic.
  • packages/compiler-cli/src/ngtsc/transform/src/transform.ts
    : AST transformation logic.
  • packages/compiler-cli/src/ngtsc/program.ts
    ：入口点（
    NgtscProgram
    ）。
  • packages/compiler-cli/src/ngtsc/core/src/compiler.ts
    ：核心逻辑（
    NgCompiler
    ）。
  • packages/compiler-cli/src/ngtsc/transform/src/trait.ts
    ：特质状态机。
  • packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts
    ：组件编译逻辑。
  • packages/compiler-cli/src/ngtsc/typecheck/src/template_type_checker.ts
    ：类型检查逻辑。
  • packages/compiler-cli/src/ngtsc/transform/src/transform.ts
    ：AST转换逻辑。