# 代码生成器

<cite>
**本文引用的文件**
- [src/codegen.rs](file://src/codegen.rs)
- [src/swc_transform.rs](file://src/swc_transform.rs)
- [src/project_compiler.rs](file://src/project_compiler.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [src/coff.rs](file://src/coff.rs)
- [src/dep_graph.rs](file://src/dep_graph.rs)
- [src/project.rs](file://src/project.rs)
- [src/tsn_ffi.rs](file://src/tsn_ffi.rs)
- [src/main.rs](file://src/main.rs)
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
- [runtime/build.rs](file://runtime/build.rs)
- [Cargo.toml](file://Cargo.toml)
- [ARCHITECTURE.md](file://ARCHITECTURE.md)
- [README.md](file://README.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 ts-native 的代码生成器，系统性阐述从 TypeScript 到 Cranelift IR 再到机器码的目标代码生成流程。重点覆盖：
- HIR（中间表示）到 Cranelift IR 的转换细节
- 函数调用约定、寄存器分配、内存访问模式与异常处理机制
- 优化策略、调试信息与性能分析
- 配置选项、扩展接口与故障排除

**更新** 本次更新新增了对 QuickJS 回退机制的支持，包括在代码生成阶段检测 fallback 包并生成 js_qjs_call 调用，以及对 native addon 配置的支持，包括 native addon 配置解析、external_functions 自动映射生成和 addon 外部调用生成逻辑。

## 项目结构
ts-native 采用模块化设计，围绕"SWC 解析 → HIR → Cranelift 代码生成 → COFF/独立可执行文件"的流水线组织：
- swc_transform：将 TypeScript AST 转换为 HIR，支持 ES6 模块、CommonJS 和导入绑定处理
- codegen：将 HIR 转换为 Cranelift IR，并生成 COFF，新增 native addon 配置传递、external_functions 自动映射和 QuickJS 回退机制
- standalone_gen：将模块数据序列化为 .tsnobj，配合 loader 生成独立可执行文件，支持 native addon DLL 加载
- project_compiler：多模块项目编译、依赖图与编译报告，支持 native addon DLL 列表收集
- dep_graph/project：模块发现、依赖解析与拓扑排序，支持 native addon 依赖识别
- tsn_ffi：导出 DLL 接口供外部 loader 调用，支持 native addon 上下文
- coff：解析/生成 COFF 对象文件（工具模块）
- runtime：运行时函数实现，包括 QuickJS 引擎集成

```mermaid
graph TB
subgraph "前端与解析"
SWC["SWC 解析器<br/>swc_transform.rs"]
HIR["HIR 中间表示<br/>codegen.rs"]
end
subgraph "代码生成"
CL["Cranelift IR 生成<br/>codegen.rs"]
MOD["ObjectModule/Module<br/>codegen.rs"]
COFF["COFF 生成<br/>coff.rs / codegen.rs"]
end
subgraph "项目与打包"
DG["依赖图<br/>dep_graph.rs"]
PRJ["项目发现<br/>project.rs"]
PC["项目编译器<br/>project_compiler.rs"]
SG["独立可执行生成<br/>standalone_gen.rs"]
end
subgraph "接口与运行时"
FFI["FFI 导出<br/>tsn_ffi.rs"]
RUNTIME["运行时函数<br/>runtime/src/lib.rs"]
BUILD["构建脚本<br/>runtime/build.rs"]
END
SWC --> HIR --> CL --> MOD --> COFF
PRJ --> DG --> PC --> SG
FFI --> SG
RUNTIME --> SG
BUILD --> RUNTIME
```

**图表来源**
- [src/swc_transform.rs:1-800](file://src/swc_transform.rs#L1-L800)
- [src/codegen.rs:1-800](file://src/codegen.rs#L1-L800)
- [src/coff.rs:1-388](file://src/coff.rs#L1-L388)
- [src/dep_graph.rs:1-257](file://src/dep_graph.rs#L1-L257)
- [src/project.rs:1-461](file://src/project.rs#L1-L461)
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)
- [src/standalone_gen.rs:1-637](file://src/standalone_gen.rs#L1-L637)
- [src/tsn_ffi.rs:1-341](file://src/tsn_ffi.rs#L1-L341)
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [runtime/src/lib.rs:1554-1737](file://runtime/src/lib.rs#L1554-L1737)
- [runtime/build.rs:1-37](file://runtime/build.rs#L1-37)

**章节来源**
- [ARCHITECTURE.md:1-184](file://ARCHITECTURE.md#L1-L184)
- [README.md:1-163](file://README.md#L1-L163)

## 核心组件
- HIR（中间表示）：定义在 codegen.rs，涵盖字面量、表达式、语句、模块导入绑定等，是代码生成的输入。
- CodeGen：核心代码生成器，负责：
  - 首次遍历收集函数签名与字符串常量，新增导入绑定处理、native addon external_functions 映射和 QuickJS fallback 包检测
  - 二次遍历生成函数体 IR，支持 native addon 外部调用生成和 QuickJS 回退调用
  - 生成 COFF 与原始模块数据（供 JIT/FFI）
- SWC 转换器：将 TypeScript 源码解析为 HIR，支持 ES6 模块、CommonJS require 和导入绑定分离
- 项目编译器：多模块编译、依赖图、报告生成，支持 native addon DLL 列表收集
- 独立可执行生成器：合并模块数据、重定位、生成 .tsnobj，支持 native addon DLL 加载
- FFI 接口：导出 DLL 函数供外部 loader 调用，支持 native addon 上下文管理
- 项目配置：支持 native_addons 配置解析、js_engine 配置和 fallback 包列表
- 运行时函数：包括 QuickJS 引擎初始化、模块调用和可用性检查

**更新** 新增了对 QuickJS 回退机制的支持，通过 js_engine 配置和 fallback 包检测，在代码生成阶段自动生成 js_qjs_call 调用。

**章节来源**
- [src/codegen.rs:80-196](file://src/codegen.rs#L80-L196)
- [src/codegen.rs:254-272](file://src/codegen.rs#L254-L272)
- [src/swc_transform.rs:10-176](file://src/swc_transform.rs#L10-L176)
- [src/project_compiler.rs:189-246](file://src/project_compiler.rs#L189-L246)
- [src/standalone_gen.rs:11-35](file://src/standalone_gen.rs#L11-L35)
- [src/tsn_ffi.rs:28-44](file://src/tsn_ffi.rs#L28-L44)
- [src/project.rs:8-26](file://src/project.rs#L8-L26)
- [runtime/src/lib.rs:1554-1737](file://runtime/src/lib.rs#L1554-L1737)

## 架构概览
下图展示从 TypeScript 到可执行文件的关键步骤与模块交互，包括新增的 FFI 桥接功能和 QuickJS 回退机制：

```mermaid
sequenceDiagram
participant TS as "TypeScript 源码"
participant SWC as "SWC 解析器"
participant HIR as "HIR"
participant CG as "CodeGen"
participant CL as "Cranelift Module"
participant OBJ as "COFF 对象"
participant PC as "项目编译器"
participant SG as "独立可执行生成"
participant RT as "运行时函数"
TS->>SWC : 解析为 AST
SWC-->>HIR : 转换为 HIR (ES6/CJS/ImportBinding)
HIR->>CG : 传入编译入口
CG->>CL : 构建签名/声明函数/收集字符串
CG->>CL : 生成函数体 IR (含 native addon 调用和 QuickJS 回退)
CG->>CL : 生成 external_functions 映射 (addon_ 前缀)
CG->>RT : 调用 js_qjs_call (fallback 包)
CL-->>OBJ : 生成 COFF
PC->>OBJ : 多模块合并/重定位
PC->>SG : 生成 .tsnobj (含 addon DLL 列表)
SG->>SG : 加载 native addon DLL
```

**图表来源**
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)
- [src/project_compiler.rs:334-382](file://src/project_compiler.rs#L334-L382)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [runtime/src/lib.rs:1618-1662](file://runtime/src/lib.rs#L1618-L1662)

## 详细组件分析

### HIR 到 Cranelift IR 的转换
- 首次遍历：收集函数签名与字符串常量，声明导出函数并建立函数 ID 映射；同时收集模块导入绑定，用于后续调用解析。新增对 native addon external_functions 的自动映射生成和 QuickJS fallback 包检测。
- 二次遍历：逐函数生成 IR，包括：
  - 控制流：if/else、while、for、return、break/continue
  - 表达式：二元/一元运算、类型判断、成员访问、索引访问、赋值
  - 异常：try/catch/finally 与 throw，通过运行时函数实现
  - 类与装饰器：类声明与方法/属性收集，构造函数与静态方法处理
  - **新增** native addon 外部调用：当 import_bindings 中的 module 是 native addon 时，自动生成 addon_ 前缀的外部符号名映射
  - **新增** QuickJS 回退调用：当模块名在 fallback 包列表中时，生成 js_qjs_call 调用

```mermaid
flowchart TD
Start(["开始编译"]) --> FirstPass["首次遍历<br/>收集函数签名/字符串常量/导入绑定<br/>(含 native addon external_functions 映射和 QuickJS fallback 检测)"]
FirstPass --> ExternalFuncs["生成 external_functions 映射<br/>addon_<包名>_<函数名>"]
FirstPass --> QJSFallback["检测 QuickJS fallback 包<br/>js_engine_fallback 列表"]
ExternalFuncs --> SecondPass["二次遍历<br/>逐函数生成 IR"]
SecondPass --> CFG["控制流生成<br/>if/while/for/return"]
SecondPass --> Expr["表达式生成<br/>二元/一元/成员/索引/赋值"]
SecondPass --> TryCatch["异常处理生成<br/>try/catch/finally/throw"]
SecondPass --> NativeAddon["native addon 调用生成<br/>addon_<包名>_<函数名>"]
SecondPass --> QJSCall["QuickJS 回退调用生成<br/>js_qjs_call(mod, fn, args)"]
CFG --> Emit["发射函数体 IR"]
Expr --> Emit
TryCatch --> Emit
NativeAddon --> Emit
QJSCall --> Emit
Emit --> Finish(["完成"])
```

**图表来源**
- [src/codegen.rs:539-586](file://src/codegen.rs#L539-L586)
- [src/codegen.rs:896-965](file://src/codegen.rs#L896-L965)
- [src/codegen.rs:968-1345](file://src/codegen.rs#L968-L1345)
- [src/codegen.rs:1347-1599](file://src/codegen.rs#L1347-L1599)
- [src/codegen.rs:1627-1641](file://src/codegen.rs#L1627-L1641)
- [src/codegen.rs:2609-2625](file://src/codegen.rs#L2609-L2625)

**章节来源**
- [src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)
- [src/codegen.rs:896-965](file://src/codegen.rs#L896-L965)
- [src/codegen.rs:968-1345](file://src/codegen.rs#L968-L1345)
- [src/codegen.rs:1347-1599](file://src/codegen.rs#L1347-L1599)
- [src/codegen.rs:1627-1641](file://src/codegen.rs#L1627-L1641)
- [src/codegen.rs:2609-2625](file://src/codegen.rs#L2609-L2625)

### 函数调用约定与符号解析
- 调用解析优先级：
  1) import_bindings：将导入的标识符转为模块.成员形式
  2) **新增** native addon 外部调用：当模块名对应 native addon 配置时，生成 addon_ 前缀的外部符号名
  3) **新增** QuickJS 回退调用：当模块名在 fallback 包列表中时，生成 js_qjs_call 调用
  4) module_symbols：跨模块函数声明为外部
  5) function_ids：本模块函数直接调用
  6) 硬编码匹配：console.log/Math.* 等
  7) 通用回退：to_runtime_fn_name("foo") → js_foo
- 参数与返回：所有函数参数与返回值使用 F64（NaN-boxed），签名统一为 F64 参数、F64 返回。

**更新** 新增了 QuickJS 回退调用的处理逻辑，通过 js_qjs_call 函数实现对 fallback 包的 JavaScript 代码执行。

```mermaid
sequenceDiagram
participant C as "调用点"
participant CG as "CodeGen"
participant MOD as "ObjectModule"
participant RT as "运行时函数/js_*/addon_*"
C->>CG : 解析调用 foo(args)
CG->>CG : 检查 import_bindings/module_symbols/function_ids
alt native addon 调用
CG->>CG : 检测 native addon 配置
CG->>CG : 生成 external_functions 映射
CG->>CG : addon_<包名>_<函数名>
CG->>RT : 调用 addon_* (F64 参数/F64 返回)
CG-->>C : 返回值
else QuickJS 回退调用
CG->>CG : 检测 fallback 包配置
CG->>CG : 生成 js_qjs_call 调用
CG->>RT : 调用 js_qjs_call(mod, fn, args)
RT-->>CG : 返回 QuickJS 执行结果
CG-->>C : 返回值
else 本模块函数
CG->>MOD : 声明/获取 FuncRef
CG-->>C : 调用 IR
else 运行时函数
CG->>MOD : 声明 js_* 函数签名
CG->>RT : 调用 js_* (F64 参数/F64 返回)
CG-->>C : 返回值
end
```

**图表来源**
- [src/codegen.rs:1581-1599](file://src/codegen.rs#L1581-L1599)
- [src/codegen.rs:290-350](file://src/codegen.rs#L290-L350)
- [src/codegen.rs:393-433](file://src/codegen.rs#L393-L433)
- [src/codegen.rs:1627-1641](file://src/codegen.rs#L1627-L1641)
- [src/codegen.rs:2609-2625](file://src/codegen.rs#L2609-L2625)
- [runtime/src/lib.rs:1618-1662](file://runtime/src/lib.rs#L1618-L1662)

**章节来源**
- [src/codegen.rs:1581-1599](file://src/codegen.rs#L1581-L1599)
- [src/codegen.rs:290-350](file://src/codegen.rs#L290-L350)
- [src/codegen.rs:393-433](file://src/codegen.rs#L393-L433)
- [src/codegen.rs:1627-1641](file://src/codegen.rs#L1627-L1641)
- [src/codegen.rs:2609-2625](file://src/codegen.rs#L2609-L2625)
- [ARCHITECTURE.md:116-125](file://ARCHITECTURE.md#L116-L125)

### 寄存器分配与内存访问模式
- 寄存器分配：Cranelift 前端（FunctionBuilder）负责 SSA 形式的变量声明与定义，变量通过 Variable 标识，由 Cranelift 后端进行寄存器/栈分配。
- 内存访问：
  - 字符串常量：编译期收集，生成 DataId 并在 IR 中通过 global_value 访问
  - 数组/对象：通过运行时函数（js_array_set/js_object_set 等）进行读写，必要时更新变量以反映扩容后的指针
  - 全局值：函数地址通过 func_addr 生成标签化的函数指针（FUNCTION_TAG）

```mermaid
classDiagram
class CodeGen {
+compile_coff(exprs)
+compile_to_raw_data(exprs)
+set_module_symbols(map)
+with_native_addons(addons)
+set_native_addons(addons)
+with_qjs_fallback(fallback)
+set_qjs_fallback(fallback)
+stats()
+source_map()
}
class Ctx {
+variables : HashMap
+module : ObjectModule
+function_ids : HashMap
+string_data : HashMap
+import_bindings : HashMap
+module_symbols : HashMap
+external_functions : HashMap
+native_addon_config : HashMap
+js_engine_fallback : Vec~String~
}
class FunctionBuilder {
+create_block()
+declare_var()
+def_var()
+ins()
}
CodeGen --> Ctx : "持有上下文"
Ctx --> FunctionBuilder : "生成 IR"
```

**图表来源**
- [src/codegen.rs:254-286](file://src/codegen.rs#L254-L286)
- [src/codegen.rs:932-940](file://src/codegen.rs#L932-L940)
- [src/codegen.rs:1354-1377](file://src/codegen.rs#L1354-L1377)

**章节来源**
- [src/codegen.rs:932-940](file://src/codegen.rs#L932-L940)
- [src/codegen.rs:1354-1377](file://src/codegen.rs#L1354-L1377)

### 异常处理机制
- try/catch/finally：通过运行时函数 js_try_begin/js_try_end/js_get_exception/js_clear_exception 实现，抛出异常通过 js_throw 设置全局异常值，捕获分支读取异常值并清理状态。
- throw：调用 js_throw 后返回 undefined，终止当前执行路径。

```mermaid
flowchart TD
Enter(["进入 try 块"]) --> TryBegin["js_try_begin()"]
TryBegin --> Branch{"是否正常返回？"}
Branch --> |是| TryBody["执行 try 体"]
TryBody --> TryEnd["js_try_end()"]
TryEnd --> Clear["js_clear_exception()"]
Clear --> Finally["执行 finally"]
Branch --> |否| Catch["读取异常值 js_get_exception()"]
Catch --> Clear2["js_clear_exception()"]
Clear2 --> CatchBody["执行 catch 体"]
CatchBody --> Finally
Finally --> Merge["跳转到合并点"]
```

**图表来源**
- [src/codegen.rs:1157-1277](file://src/codegen.rs#L1157-L1277)

**章节来源**
- [src/codegen.rs:1157-1277](file://src/codegen.rs#L1157-L1277)

### 优化策略与调试信息
- 优化策略：
  - 数值比较优化：当左右两侧均为字面量时，直接使用 fcmp 与 select，避免运行时函数调用
  - 短路求值：逻辑与/或使用条件分支与合并块，正确处理 NaN-boxed 布尔值
  - fmod：使用运行时 js_fmod，Cranelift 无原生 fmod 指令
  - **新增** native addon 调用优化：通过直接的外部函数调用替代复杂的属性访问，使用 addon_ 前缀的符号名
  - **新增** QuickJS 回退调用优化：通过 js_qjs_call 函数直接调用，避免多次符号解析开销
- 调试信息：
  - SourceMap：记录代码偏移与源码位置（函数名、行列号、节点类型）
  - 编译统计：解析时间、代码生成时间、COFF 生成时间、提取时间、函数数量、字符串数量、代码/数据大小
  - 日志：编译性能统计与 SourceMap 摘要

**更新** 新增了对 native addon 调用和 QuickJS 回退调用的优化处理，通过直接的外部函数调用提升性能。

**章节来源**
- [src/codegen.rs:1401-1440](file://src/codegen.rs#L1401-L1440)
- [src/codegen.rs:488-510](file://src/codegen.rs#L488-L510)
- [src/codegen.rs:240-252](file://src/codegen.rs#L240-L252)
- [src/tsn_ffi.rs:191-205](file://src/tsn_ffi.rs#L191-L205)

### 从 HIR 到 Cranelift IR 的示例路径
- 函数声明与参数：[src/codegen.rs:896-965](file://src/codegen.rs#L896-L965)
- 表达式求值（二元/一元/成员/索引）：[src/codegen.rs:1347-1599](file://src/codegen.rs#L1347-L1599)
- 语句控制流（if/while/for/return）：[src/codegen.rs:968-1104](file://src/codegen.rs#L968-L1104)
- 异常处理（try/catch/finally/throw）：[src/codegen.rs:1157-1293](file://src/codegen.rs#L1157-L1293)
- **新增** native addon 外部调用生成：[src/codegen.rs:599-609](file://src/codegen.rs#L599-L609)
- **新增** QuickJS 回退调用生成：[src/codegen.rs:2609-2625](file://src/codegen.rs#L2609-L2625)

**章节来源**
- [src/codegen.rs:896-965](file://src/codegen.rs#L896-L965)
- [src/codegen.rs:968-1104](file://src/codegen.rs#L968-L1104)
- [src/codegen.rs:1157-1293](file://src/codegen.rs#L1157-L1293)
- [src/codegen.rs:1347-1599](file://src/codegen.rs#L1347-L1599)
- [src/codegen.rs:599-609](file://src/codegen.rs#L599-L609)
- [src/codegen.rs:2609-2625](file://src/codegen.rs#L2609-L2625)

### 代码生成器配置与扩展接口
- 配置选项：
  - Cranelift 设置：use_colocated_libcalls=false、is_pic=false
  - 特性开关：native-linker（原生 PE 链接器）、coff（COFF 相关功能）
  - **新增** native addon 配置：通过 ts-native.toml 配置 native_addons 段落，支持 DLL 文件名和函数映射
  - **新增** QuickJS 引擎配置：通过 js_engine 段落配置 enabled 和 fallback 包列表
- 扩展接口：
  - FFI 导出：tsn_compile、tsn_free_result、tsn_version、tsn_compile_coff（feature=coff）
  - 项目编译器：多模块编译、依赖图、报告生成
  - 独立可执行生成：合并模块数据、重定位、生成 .tsnobj，支持 native addon DLL 加载
  - **新增** 运行时函数：js_qjs_init、js_qjs_eval、js_qjs_call、js_qjs_is_available

**更新** 新增了对 QuickJS 引擎配置和运行时函数的支持，以及对 native addon 配置的支持。

**章节来源**
- [src/codegen.rs:525-530](file://src/codegen.rs#L525-L530)
- [Cargo.toml:53-57](file://Cargo.toml#L53-L57)
- [src/tsn_ffi.rs:60-170](file://src/tsn_ffi.rs#L60-L170)
- [src/project_compiler.rs:205-332](file://src/project_compiler.rs#L205-L332)
- [src/standalone_gen.rs:390-605](file://src/standalone_gen.rs#L390-L605)
- [runtime/src/lib.rs:1554-1737](file://runtime/src/lib.rs#L1554-L1737)

### QuickJS 引擎配置与集成
- **新增** JsEngineConfig 结构体：包含 enabled 标志和 fallback 包列表，支持 TypeScript 函数到 JavaScript 代码的回退执行
- **新增** ts-native.toml 配置格式：
  ```
  [js-engine]
  enabled = true
  fallback = ["express", "axios", "koa"]
  ```
- **新增** 配置解析逻辑：支持 js-engine 段落解析，包括 enabled 和 fallback 数组的处理
- **新增** 运行时函数集成：js_qjs_init、js_qjs_eval、js_qjs_call、js_qjs_is_available 等函数
- **新增** 构建脚本：runtime/build.rs 支持 QuickJS C 源码编译

**更新** 新增了完整的 QuickJS 引擎配置解析、运行时函数集成和构建支持。

**章节来源**
- [src/project.rs:18-25](file://src/project.rs#L18-L25)
- [src/project.rs:287-304](file://src/project.rs#L287-L304)
- [src/project.rs:1350-1378](file://src/project.rs#L1350-L1378)
- [runtime/src/lib.rs:1554-1737](file://runtime/src/lib.rs#L1554-L1737)
- [runtime/build.rs:1-37](file://runtime/build.rs#L1-37)

### QuickJS 回退调用生成机制
- **新增** fallback 包检测：在 import_bindings 处理时检查模块名是否在 js_engine_fallback 列表中
- **新增** js_qjs_call 调用生成：当检测到 fallback 包时，生成 js_qjs_call 调用，参数包括模块名、函数名和参数数组
- **新增** 参数打包：将调用参数打包为数组，通过 js_array_new 和 js_array_push 运行时函数处理
- **新增** 符号命名规则：使用 js_qjs_call 作为回退调用的统一入口

**更新** 新增了完整的 QuickJS 回退调用生成机制，支持对 fallback 包的 JavaScript 代码执行。

**章节来源**
- [src/codegen.rs:2609-2625](file://src/codegen.rs#L2609-L2625)
- [src/codegen.rs:985-986](file://src/codegen.rs#L985-L986)
- [src/codegen.rs:542-551](file://src/codegen.rs#L542-L551)

### native addon 配置与解析
- **新增** NativeAddonConfig 结构体：包含 DLL 文件名和函数映射，支持 TypeScript 函数名到 C/C++ 导出函数名的转换
- **新增** ts-native.toml 配置格式：
  ```
  [native_addons.sharp]
  dll = "sharp.dll"
  
  [native_addons.sharp.functions]
  resize = "sharp_resize"
  rotate = "sharp_rotate"
  ```
- **新增** 配置解析逻辑：支持 [native_addons.XXX] 和 [native_addons.XXX.functions] 两种格式的解析

**更新** 新增了完整的 native addon 配置解析和映射生成机制。

**章节来源**
- [src/project.rs:8-26](file://src/project.rs#L8-L26)
- [src/project.rs:199-313](file://src/project.rs#L199-L313)
- [src/project.rs:884-931](file://src/project.rs#L884-L931)

### native addon 外部函数映射生成
- **新增** external_functions 自动映射：当 import_bindings 中的模块名对应 native addon 配置时，自动生成 addon_ 前缀的外部符号名
- **新增** 符号命名规则：addon_<包名>_<函数名>，如 addon_sharp_resize
- **新增** 代码生成逻辑：在首次遍历时收集 native addon 的 external_functions 映射

**更新** 新增了 native addon 外部函数映射的自动生成机制。

**章节来源**
- [src/codegen.rs:599-609](file://src/codegen.rs#L599-L609)
- [src/codegen.rs:531-540](file://src/codegen.rs#L531-L540)

### 项目编译器与独立可执行生成的 FFI 支持
- **新增** addon DLL 列表收集：项目编译器从项目配置中收集所有 native addon 的 DLL 文件名
- **新增** .tsnobj 序列化：独立可执行生成器将 addon DLL 列表序列化到 .tsnobj 文件中
- **新增** 运行时加载：独立可执行文件启动时自动加载配置的 native addon DLL

**更新** 新增了对 native addon DLL 的完整生命周期支持。

**章节来源**
- [src/project_compiler.rs:549-554](file://src/project_compiler.rs#L549-L554)
- [src/standalone_gen.rs:136-168](file://src/standalone_gen.rs#L136-L168)

## 依赖分析
- 模块发现与解析：project.rs 扫描目录、识别入口、解析 import 路径（用户模块优先于内置模块），**新增** native addon 包识别和 QuickJS fallback 包识别
- 依赖图：dep_graph.rs 基于 import/export 构建 DAG，拓扑排序确定编译顺序，计算入口依赖闭包，**改进** native addon 依赖处理
- 项目编译：project_compiler.rs 协调多模块编译、合并对象文件、生成独立可执行文件，**新增** native addon DLL 列表收集
- FFI 桥接：tsn_ffi.rs 提供 DLL 接口，支持 native addon 上下文管理
- **新增** 运行时集成：runtime/src/lib.rs 提供 QuickJS 引擎集成和相关运行时函数

```mermaid
graph LR
PRJ["project.rs<br/>(含 native addon 和 QuickJS 支持)"] --> DG["dep_graph.rs<br/>(识别 native addon 和 fallback 依赖)"]
DG --> PC["project_compiler.rs<br/>(收集 addon DLL 列表)"]
PC --> SG["standalone_gen.rs<br/>(加载 addon DLL)"]
SWC["swc_transform.rs<br/>(ImportBinding 分离)"] --> CG["codegen.rs<br/>(native addon external_functions 映射和 QuickJS 回退)"]
CG --> COFF["coff.rs"]
PC --> COFF
RUNTIME["runtime/src/lib.rs<br/>(QuickJS 引擎集成)"] --> CG
```

**图表来源**
- [src/project.rs:58-153](file://src/project.rs#L58-L153)
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)
- [src/project_compiler.rs:205-332](file://src/project_compiler.rs#L205-L332)
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:521-604](file://src/codegen.rs#L521-L604)
- [src/coff.rs:1-388](file://src/coff.rs#L1-L388)
- [runtime/src/lib.rs:1554-1737](file://runtime/src/lib.rs#L1554-L1737)

**章节来源**
- [src/project.rs:58-153](file://src/project.rs#L58-L153)
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)
- [src/project_compiler.rs:205-332](file://src/project_compiler.rs#L205-L332)

## 性能考虑
- 编译阶段计时与内存估算：项目编译器提供阶段耗时与内存使用统计，便于定位瓶颈
- 优化建议：
  - 避免不必要的运行时函数调用（如 fmod、严格相等等）
  - 合理使用短路求值与条件选择，减少分支开销
  - 控制字符串常量数量，减少数据段大小
  - 使用 Cranelift 设置优化（如关闭 colocated libcalls、非 PIC）
  - **新增** 利用 native addon 的直接调用优化，避免复杂的属性访问开销
  - **新增** 通过 external_functions 映射减少符号解析开销
  - **新增** QuickJS 回退调用的批量参数处理优化，减少数组操作开销
  - **新增** fallback 包的预检测机制，避免重复的包名检查

**更新** 新增了对 native addon 调用优化和 QuickJS 回退调用优化的考虑。

**章节来源**
- [src/project_compiler.rs:27-52](file://src/project_compiler.rs#L27-L52)
- [src/project_compiler.rs:54-121](file://src/project_compiler.rs#L54-L121)
- [src/codegen.rs:525-530](file://src/codegen.rs#L525-L530)

## 故障排除指南
- 常见问题与定位：
  - 解析错误：检查 TypeScript 语法与 SWC 版本兼容性
  - 编译错误：查看 CodeGen 错误信息与 SourceMap 摘要
  - 运行时符号未解析：确认模块符号表与导入绑定是否正确
  - 重定位失败：检查 .tsnobj 符号与重定位表
  - **新增** native addon 调用失败：检查 ts-native.toml 中的 native_addons 配置是否正确
  - **新增** addon DLL 加载失败：检查 DLL 文件是否存在且与目标平台兼容
  - **新增** QuickJS 回退调用失败：检查 js_engine 配置和 fallback 包列表
  - **新增** QuickJS 引擎初始化失败：检查 QuickJS 构建是否成功
- 排查步骤：
  - 启用日志：TSN_LOG 环境变量
  - 使用 CLI：ts-native build ./my-project
  - 检查编译报告：总耗时、内存使用、函数覆盖率、代码/数据大小
  - 验证 COFF：使用 coff.rs 解析器验证节区、符号与重定位
  - **新增** 检查 native addon 配置：确认 ts-native.toml 中的 native_addons 段落配置正确
  - **新增** 验证 external_functions 映射：确认 addon_ 前缀的符号名生成正确
  - **新增** 检查 QuickJS 配置：确认 js_engine.enabled 和 fallback 列表配置正确
  - **新增** 验证运行时函数：确认 js_qjs_call 等运行时函数可用

**更新** 新增了对 QuickJS 相关问题的排查指导。

**章节来源**
- [src/tsn_ffi.rs:60-81](file://src/tsn_ffi.rs#L60-L81)
- [src/main.rs:7-78](file://src/main.rs#L7-L78)
- [src/project_compiler.rs:662-701](file://src/project_compiler.rs#L662-L701)
- [src/coff.rs:72-231](file://src/coff.rs#L72-L231)

## 结论
ts-native 的代码生成器以 HIR 为核心，借助 Cranelift 将 TypeScript 编译为高效的 x86-64 机器码。通过 NaN-boxing 值模型、完善的异常处理与运行时函数桥接，实现了对 JavaScript 语义的近似原生性能。**最新更新**增强了对外部库、运行时函数和 JavaScript 引擎的集成能力，通过 native addon 配置解析、external_functions 自动映射生成、addon 外部调用生成逻辑和 QuickJS 回退机制，实现了完整的 FFI 桥接功能。项目提供了可观测性、多模块编译与独立可执行生成能力，适合构建高性能的 AOT 编译链路和原生扩展开发环境。

## 附录
- CLI 使用：[src/main.rs:7-78](file://src/main.rs#L7-L78)
- 架构总览：[ARCHITECTURE.md:1-184](file://ARCHITECTURE.md#L1-L184)
- 功能特性与限制：[README.md:64-88](file://README.md#L64-L88)