# 运行时系统

<cite>
**本文引用的文件**
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
- [runtime/build.rs](file://runtime/build.rs)
- [runtime/Cargo.toml](file://runtime/Cargo.toml)
- [src/tsn_ffi.rs](file://src/tsn_ffi.rs)
- [src/codegen.rs](file://src/codegen.rs)
- [src/swc_transform.rs](file://src/swc_transform.rs)
- [src/project.rs](file://src/project.rs)
- [loader/src/main.rs](file://loader/src/main.rs)
- [Cargo.toml](file://Cargo.toml)
- [docs/NODE_MODULE_SUPPORT_PROPOSAL.md](file://docs/NODE_MODULE_SUPPORT_PROPOSAL.md)
- [tsn_abi.h](file://tsn_abi.h)
- [docs/README.md](file://docs/README.md)
</cite>

## 更新摘要
**变更内容**
- 新增 QuickJS 引擎集成作为纯 JavaScript npm 包的回退执行机制
- 外部 crate 替代自定义实现，包括 uuid、chrono 等库的集成
- 新增 js-engine 配置支持，实现渐进式模块兼容方案
- 增强运行时函数族，支持更多标准库功能
- 完善编译器与运行时的协作机制，支持多种包类型的处理

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

## 简介
本文件面向 ts-native 的运行时系统，系统由两部分组成：
- 运行时库（Rust 实现，导出为 C ABI 的动态库，供加载器按需调用）
- 编译器前端与后端（Rust 实现，负责 TypeScript 解析、中间表示、代码生成与链接）

运行时系统的核心职责包括：
- 提供 JavaScript 语义的运行时函数（字符串、数组、对象、数学、JSON、文件系统等）
- 以 NaN-boxing 方式表示 JS 值，实现紧凑的值包装与类型识别
- 通过 FFI 接口暴露给加载器，完成模块编译、重定位与执行
- 与编译器生成的代码协作，确保符号解析与调用约定一致
- **新增**：支持 QuickJS 引擎作为纯 JavaScript npm 包的回退执行机制
- **新增**：集成外部 crate 替代自定义实现，提升性能和稳定性

## 项目结构
仓库采用多 crate 组织方式：
- runtime：运行时库，导出 C ABI 函数，实现 JS 值表示与运行时操作，支持 QuickJS 集成
- src：编译器与工具链，包含 TypeScript 解析、中间表示、代码生成、加载器等
- loader：Windows 下的运行时加载器，负责加载运行时插件、应用重定位并执行入口
- docs：文档入口

```mermaid
graph TB
subgraph "编译器侧"
SWC["SWC 解析器<br/>src/swc_transform.rs"]
CG["代码生成器<br/>src/codegen.rs"]
FFIBridge["FFI 桥接<br/>src/tsn_ffi.rs"]
ABI["ABI 头文件<br/>tsn_abi.h"]
Project["项目管理<br/>src/project.rs"]
End
subgraph "运行时侧"
RT["运行时库<br/>runtime/src/lib.rs"]
QuickJS["QuickJS 引擎<br/>runtime/build.rs"]
End
subgraph "加载器"
LDR["加载器<br/>loader/src/main.rs"]
end
SWC --> CG
CG --> FFIBridge
FFIBridge --> ABI
ABI --> LDR
LDR --> RT
RT --> QuickJS
```

**图表来源**
- [src/swc_transform.rs:1-200](file://src/swc_transform.rs#L1-L200)
- [src/codegen.rs:1-200](file://src/codegen.rs#L1-L200)
- [src/tsn_ffi.rs:1-341](file://src/tsn_ffi.rs#L1-L341)
- [src/project.rs:1-200](file://src/project.rs#L1-L200)
- [loader/src/main.rs:1-200](file://loader/src/main.rs#L1-L200)
- [runtime/src/lib.rs:1-800](file://runtime/src/lib.rs#L1-L800)
- [runtime/build.rs:1-37](file://runtime/build.rs#L1-L37)
- [tsn_abi.h:1-92](file://tsn_abi.h#L1-L92)

**章节来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [runtime/Cargo.toml:1-39](file://runtime/Cargo.toml#L1-L39)
- [docs/README.md:1-9](file://docs/README.md#L1-L9)

## 核心组件
- NaN-boxing 值表示系统
  - 使用 f64 的高位作为类型标签，低 48 位承载索引或位值
  - 支持 number、string、object、boolean、undefined、null、function、array 等类型
  - 提供类型判断、值池访问与严格相等比较
- 运行时函数集合
  - 字符串：创建、长度、字符编码
  - 数组：新建、push、索引读写、长度
  - 对象：新建、属性读写、keys/values/entries/assign/hasOwn/isArray/from
  - 数学：三角、平方根、绝对值、取整、幂、随机
  - JSON：stringify/parse
  - 类型：typeof
  - 文件系统：读写/追加/存在性/目录/状态/复制/重命名/真实路径
  - 路径处理：join/resolve/dirname/basename/extname/isAbsolute/normalize/sep/delimiter
  - 操作系统：platform/type/arch/hostname/homedir/tmpdir/totalmem/freemem/uptime/eol/endian/release/version/machine/networkInterfaces/userInfo/constants/devNull/loadavg/cpus
  - 进程：cwd/chdir/exit/pid/ppid/platform/arch/version/env/envGet/argv/execPath/hrtime/memoryUsage/uptime/title/nextTick
  - 定时器：setTimeout/setInterval/clearTimeout/clearInterval/setImmediate/clearImmediate
  - 加密：randomBytes/randomUUID/createHash/hash/update/digest/getHashes/getCiphers/timingSafeEqual/pbkdf2
  - 压缩：deflate/inflate/gzip/gunzip
  - 日期：now/parse/utc
  - 工具：format/inspect
  - **新增**：QuickJS 引擎：init、eval、is_available 等接口
- FFI 接口
  - 编译 API：tsn_compile、tsn_free_result、tsn_version、tsn_compile_coff、tsn_free_coff
  - 编译结果结构：包含代码/数据/rdata 段、符号表、重定位表、错误信息
- 加载器
  - 动态加载运行时插件（如 runtime.dll）
  - 分配可执行内存，复制代码与数据，应用重定位
  - 查找入口函数（main），调用并返回结果
- **新增**：项目配置系统
  - 支持 js-engine 配置，启用 QuickJS 回退机制
  - 支持 fallback 包列表配置
  - 支持外部 crate 集成配置

**章节来源**
- [runtime/src/lib.rs:1-2544](file://runtime/src/lib.rs#L1-L2544)
- [runtime/build.rs:1-37](file://runtime/build.rs#L1-L37)
- [runtime/Cargo.toml:28-30](file://runtime/Cargo.toml#L28-L30)
- [src/tsn_ffi.rs:1-341](file://src/tsn_ffi.rs#L1-L341)
- [src/project.rs:18-25](file://src/project.rs#L18-L25)
- [loader/src/main.rs:1-1260](file://loader/src/main.rs#L1-L1260)

## 架构总览
运行时系统围绕"编译器生成的二进制 + 运行时插件"协同工作，新增 QuickJS 引擎支持：
- 编译阶段：SWC 解析 TypeScript，生成中间表示；Cranelift 生成目标代码；导出符号与重定位
- 运行阶段：加载器将代码与数据复制到内存，应用重定位；从运行时插件解析外部符号（如 js_* 函数）；调用入口函数
- **新增**：QuickJS 集成：当启用 js-engine 功能时，运行时可加载 QuickJS 引擎执行纯 JavaScript 包

```mermaid
sequenceDiagram
participant Loader as "加载器"
participant Compiler as "编译器DLL"
participant Runtime as "运行时插件"
participant QuickJS as "QuickJS 引擎"
participant ExecMem as "可执行内存"
Loader->>Compiler : 调用 tsn_compile(source)
Compiler-->>Loader : 返回 TsnCompileResult代码/数据/符号/重定位
Loader->>ExecMem : 分配并复制代码段
Loader->>ExecMem : 分配并复制数据段
Loader->>ExecMem : 应用重定位内部/外部符号
Loader->>Runtime : 解析外部符号js_*
alt 启用 QuickJS
Runtime->>QuickJS : 初始化引擎
Runtime->>QuickJS : 执行回退包代码
end
Loader->>ExecMem : 调用入口函数 main()
ExecMem-->>Loader : 返回 f64 结果
```

**图表来源**
- [src/tsn_ffi.rs:60-106](file://src/tsn_ffi.rs#L60-L106)
- [loader/src/main.rs:387-508](file://loader/src/main.rs#L387-L508)
- [loader/src/main.rs:535-743](file://loader/src/main.rs#L535-L743)
- [runtime/src/lib.rs:1554-1672](file://runtime/src/lib.rs#L1554-L1672)

## 详细组件分析

### NaN-boxing 值表示系统
- 类型标签与布局
  - 高 4 位作为类型标签，低 48 位承载索引或位值
  - 支持 number、string、object、boolean、undefined、null、function、array
- 值池与索引寻址
  - 字符串、数组、对象分别维护独立池，值以 tagged f64 形式持有
  - 访问时根据标签解包索引，从池中读取实际对象
- 类型判断与严格相等
  - 通过位运算快速判断类型
  - 严格相等：同位相等直接为真；字符串类型比较内容

```mermaid
flowchart TD
Start(["输入 f64 值"]) --> CheckNaN["是否为 NaN?"]
CheckNaN --> |否| IsNumber["判定为 number"]
CheckNaN --> |是| ExtractTag["提取高 4 位标签"]
ExtractTag --> TagZero{"标签==0?"}
TagZero --> |是| IsNumber
TagZero --> |否| SwitchTag{"分支: 标签类型"}
SwitchTag --> |字符串| GetString["从字符串池取值"]
SwitchTag --> |数组| GetArray["从数组池取值"]
SwitchTag --> |对象| GetObject["从对象池取值"]
SwitchTag --> |布尔/未定义/空/函数| ReturnTagged["返回对应 tagged 值"]
```

**图表来源**
- [runtime/src/lib.rs:21-35](file://runtime/src/lib.rs#L21-L35)
- [runtime/src/lib.rs:41-60](file://runtime/src/lib.rs#L41-L60)
- [runtime/src/lib.rs:72-103](file://runtime/src/lib.rs#L72-L103)
- [runtime/src/lib.rs:114-133](file://runtime/src/lib.rs#L114-L133)

**章节来源**
- [runtime/src/lib.rs:7-24](file://runtime/src/lib.rs#L7-L24)
- [runtime/src/lib.rs:26-35](file://runtime/src/lib.rs#L26-L35)
- [runtime/src/lib.rs:41-60](file://runtime/src/lib.rs#L41-L60)
- [runtime/src/lib.rs:72-103](file://runtime/src/lib.rs#L72-L103)
- [runtime/src/lib.rs:114-133](file://runtime/src/lib.rs#L114-L133)

### 运行时函数族：字符串、数组、对象、数学、JSON、文件系统
- 字符串
  - 从静态 C 字符串创建 JS 字符串
  - 长度与字符编码（fromCharCode）
- 数组
  - 新建、push、索引读写、长度
- 对象
  - 新建、属性读写、keys/values/entries/assign/hasOwn/isArray/from
- 数学与随机
  - 三角、平方根、绝对值、取整、幂、随机
- JSON
  - stringify/parse（简化实现）
- 文件系统
  - 同步/异步读写、追加、存在性、目录、状态、复制、重命名、真实路径
- 路径处理
  - join/resolve/dirname/basename/extname/isAbsolute/normalize/sep/delimiter
- 操作系统
  - platform/type/arch/hostname/homedir/tmpdir/totalmem/freemem/uptime/eol/endian/release/version/machine/networkInterfaces/userInfo/constants/devNull/loadavg/cpus
- 进程
  - cwd/chdir/exit/pid/ppid/platform/arch/version/env/envGet/argv/execPath/hrtime/memoryUsage/uptime/title/nextTick
- 定时器
  - setTimeout/setInterval/clearTimeout/clearInterval/setImmediate/clearImmediate
- 加密
  - randomBytes/randomUUID/createHash/hash/update/digest/getHashes/getCiphers/timingSafeEqual/pbkdf2
  - **新增**：使用外部 crate 替代自定义实现，提升性能
- 压缩
  - deflate/inflate/gzip/gunzip
- 日期
  - now/parse/utc
  - **新增**：集成 chrono crate，提供标准日期时间功能
- 工具
  - format/inspect

```mermaid
classDiagram
class JsArray {
+elements : Vec<f64>
+length : usize
}
class JsObject {
+properties : HashMap<u64, f64>
}
class RuntimeAPIs {
+js_string_from_static(ptr) f64
+js_array_new(cap) f64
+js_array_push(arr, elem) f64
+js_index_get(obj, idx) f64
+js_object_new() f64
+js_object_set(obj, key, val) f64
+js_object_get(obj, key) f64
+js_math_*() f64
+js_json_stringify(val) f64
+js_fs_*() f64
+js_set_log_callback(cb)
+js_qjs_*() f64
}
RuntimeAPIs --> JsArray : "使用"
RuntimeAPIs --> JsObject : "使用"
```

**图表来源**
- [runtime/src/lib.rs:65-68](file://runtime/src/lib.rs#L65-L68)
- [runtime/src/lib.rs:108-110](file://runtime/src/lib.rs#L108-L110)
- [runtime/src/lib.rs:137-199](file://runtime/src/lib.rs#L137-L199)
- [runtime/src/lib.rs:224-323](file://runtime/src/lib.rs#L224-L323)
- [runtime/src/lib.rs:325-364](file://runtime/src/lib.rs#L325-L364)
- [runtime/src/lib.rs:366-402](file://runtime/src/lib.rs#L366-L402)
- [runtime/src/lib.rs:471-506](file://runtime/src/lib.rs#L471-L506)
- [runtime/src/lib.rs:646-780](file://runtime/src/lib.rs#L646-L780)
- [runtime/src/lib.rs:1554-1672](file://runtime/src/lib.rs#L1554-L1672)

**章节来源**
- [runtime/src/lib.rs:137-2544](file://runtime/src/lib.rs#L137-L2544)

### QuickJS 引擎集成
**新增**：作为纯 JavaScript npm 包的回退执行机制

- 引擎初始化与管理
  - js_qjs_init：初始化 QuickJS 引擎（条件编译，仅在启用 quickjs feature 时有效）
  - js_qjs_is_available：检查 QuickJS 引擎可用性
  - 引擎状态管理：全局 Runtime 和 Context，单线程使用
- 代码执行接口
  - js_qjs_eval：在 QuickJS 中执行 JavaScript 代码并返回结果
  - 值转换：QuickJS QjsValue ↔ NaN-tagged f64
- 集成特点
  - 条件编译：通过 quickjs feature 控制启用/禁用
  - 性能权衡：相比原生实现约 10-100x 慢，但提供 95% 纯 JS 包支持
  - 值转换：支持 undefined、null、boolean、number、string、object 等类型转换

```mermaid
flowchart TD
Init["初始化 QuickJS"] --> CheckFeature{"检查 quickjs feature"}
CheckFeature --> |启用| CreateRT["创建 Runtime"]
CheckFeature --> |禁用| ReturnFalse["返回 0.0"]
CreateRT --> CreateCtx["创建 Context"]
CreateCtx --> Ready["引擎就绪"]
Ready --> Eval["执行 JavaScript 代码"]
Eval --> Convert["值转换 QjsValue ↔ NaN-tagged"]
Convert --> Return["返回结果"]
```

**图表来源**
- [runtime/src/lib.rs:1554-1672](file://runtime/src/lib.rs#L1554-L1672)
- [runtime/src/lib.rs:1676-1894](file://runtime/src/lib.rs#L1676-L1894)
- [runtime/build.rs:6-37](file://runtime/build.rs#L6-L37)

**章节来源**
- [runtime/src/lib.rs:1554-1894](file://runtime/src/lib.rs#L1554-L1894)
- [runtime/build.rs:1-37](file://runtime/build.rs#L1-L37)
- [runtime/Cargo.toml:37-39](file://runtime/Cargo.toml#L37-L39)

### 项目配置与模块兼容方案
**新增**：支持 js-engine 配置和渐进式模块兼容

- 配置结构
  - JsEngineConfig：包含 enabled 和 fallback 列表
  - 支持在 toml 配置文件中启用和配置
- 模块解析增强
  - resolve_import：支持 node_modules 解析
  - fallback 机制：对不在 fallback 列表中的包使用原生路径
- 编译器集成
  - codegen：支持 js_engine_fallback 配置传递
  - 生成对应的外部符号和调用代码

```mermaid
flowchart TD
Config["读取 toml 配置"] --> Parse["解析 js-engine section"]
Parse --> Enabled{"enabled = true?"}
Enabled --> |是| LoadFallback["加载 fallback 包列表"]
Enabled --> |否| Skip["跳过 QuickJS 集成"]
LoadFallback --> Resolve["模块解析"]
Resolve --> CheckFallback{"包在 fallback 列表中?"}
CheckFallback --> |是| UseQJS["使用 QuickJS 执行"]
CheckFallback --> |否| UseNative["使用原生实现"]
UseQJS --> Generate["生成回退调用代码"]
UseNative --> Generate
Generate --> Compile["编译到目标代码"]
```

**图表来源**
- [src/project.rs:18-25](file://src/project.rs#L18-L25)
- [src/project.rs:201-313](file://src/project.rs#L201-L313)
- [src/codegen.rs:542-551](file://src/codegen.rs#L542-L551)

**章节来源**
- [src/project.rs:18-25](file://src/project.rs#L18-L25)
- [src/project.rs:201-313](file://src/project.rs#L201-L313)
- [src/codegen.rs:542-551](file://src/codegen.rs#L542-L551)

### FFI 接口设计与实现
- 导出函数
  - tsn_compile：编译 TypeScript 源为 TSN 模块，返回编译结果
  - tsn_free_result：释放编译结果及其内部内存
  - tsn_version：返回版本字符串
  - tsn_compile_coff（可选）：输出标准 COFF 字节流
  - tsn_free_coff（可选）：释放 COFF 字节流
- 编译结果结构
  - 代码/数据/rdata 指针与长度
  - 符号表与重定位表（含节区、偏移、目标名）
  - 错误信息、行列号与上下文
- 错误处理
  - 统一构造错误结果，提取行号与上下文

```mermaid
sequenceDiagram
participant Client as "调用方"
participant DLL as "ts-native.dll"
participant Bridge as "FFI 桥接"
participant CG as "代码生成器"
Client->>DLL : tsn_compile(source)
DLL->>Bridge : 参数校验与初始化
Bridge->>CG : 解析/生成/打包
CG-->>Bridge : 原始模块数据
Bridge-->>DLL : 构造 TsnCompileResult
DLL-->>Client : 返回结果指针
Client->>DLL : tsn_free_result(result)
DLL->>Bridge : 释放内部内存
Bridge-->>DLL : 完成
```

**图表来源**
- [src/tsn_ffi.rs:60-106](file://src/tsn_ffi.rs#L60-L106)
- [src/tsn_ffi.rs:172-292](file://src/tsn_ffi.rs#L172-L292)
- [src/codegen.rs:19-43](file://src/codegen.rs#L19-L43)

**章节来源**
- [src/tsn_ffi.rs:1-341](file://src/tsn_ffi.rs#L1-L341)
- [src/codegen.rs:19-43](file://src/codegen.rs#L19-L43)
- [tsn_abi.h:1-92](file://tsn_abi.h#L1-L92)

### 加载器与运行时插件集成
- 插件加载
  - 通过 Windows API 动态加载运行时插件（如 runtime.dll）
  - 缓存符号地址，避免重复查询
- 内存分配与复制
  - 分配可执行内存与数据内存，复制代码与数据段
- 重定位应用
  - 支持 REL32 与 ADDR64 两种重定位类型
  - 内部符号：节内偏移；外部符号：从插件解析
- 入口调用
  - 查找 main 符号，转换为函数指针并调用
  - 返回 f64 结果

```mermaid
flowchart TD
A["加载运行时插件"] --> B["分配可执行内存"]
B --> C["复制代码段"]
C --> D["分配数据内存"]
D --> E["复制数据段"]
E --> F["应用重定位内部/外部"]
F --> G["查找入口 main"]
G --> H["调用入口并返回结果"]
```

**图表来源**
- [loader/src/main.rs:557-743](file://loader/src/main.rs#L557-L743)
- [loader/src/main.rs:270-333](file://loader/src/main.rs#L270-L333)

**章节来源**
- [loader/src/main.rs:130-1260](file://loader/src/main.rs#L130-L1260)

### 编译器与运行时的协作
- 中间表示与代码生成
  - SWC 解析 TypeScript，生成 HIR
  - CodeGen 将 HIR 映射为 Cranelift IR，并生成目标代码
  - 导出符号与重定位，便于运行时插件中的外部调用
- NaN-boxing 在生成代码中的使用
  - 生成代码中使用 is_truthy、UNDEFINED/NULL/TRUE/FALSE 等常量
  - 短路求值与条件分支正确处理 NaN-boxed 布尔值
- **新增**：QuickJS 集成支持
  - 生成 js_engine_call 外部符号
  - 支持 fallback 包的动态调用

```mermaid
sequenceDiagram
participant TS as "TypeScript 源码"
participant SWC as "SWC 解析器"
participant CG as "代码生成器"
participant RT as "运行时插件"
participant Exec as "执行引擎"
TS->>SWC : 解析为 AST
SWC->>CG : 转换为 HIR
CG->>RT : 导出符号js_*
CG->>Exec : 生成代码/重定位
alt 启用 QuickJS
CG->>RT : 导出符号tsn_js_engine_call
end
Exec->>RT : 解析外部符号并调用
```

**图表来源**
- [src/swc_transform.rs:10-34](file://src/swc_transform.rs#L10-L34)
- [src/codegen.rs:417-449](file://src/codegen.rs#L417-L449)
- [runtime/src/lib.rs:137-2544](file://runtime/src/lib.rs#L137-L2544)

**章节来源**
- [src/swc_transform.rs:1-200](file://src/swc_transform.rs#L1-L200)
- [src/codegen.rs:417-449](file://src/codegen.rs#L417-L449)
- [runtime/src/lib.rs:137-2544](file://runtime/src/lib.rs#L137-L2544)

## 依赖关系分析
- 运行时库依赖
  - Rust 标准库与第三方加密、压缩、随机等库
  - **新增**：uuid、chrono 等外部 crate 替代自定义实现
- 编译器依赖
  - SWC 生态（解析/AST/遍历）、Cranelift（IR/模块/对象）、object（解析 COFF）
- 加载器依赖
  - Windows API（动态库加载、内存管理、符号解析）
- **新增**：QuickJS 依赖
  - 通过 build.rs 条件编译 QuickJS C 源码
  - 仅在 quickjs feature 启用时编译

```mermaid
graph LR
RTLib["运行时库<br/>runtime/src/lib.rs"] --> Std["Rust 标准库"]
RTLib --> Ext["第三方库加密/压缩/随机"]
RTLib --> UUID["uuid crate"]
RTLib --> Chrono["chrono crate"]
Compiler["编译器<br/>src/codegen.rs"] --> SWC["SWC 生态"]
Compiler --> CL["Cranelift"]
Compiler --> OBJ["object"]
Loader["加载器<br/>loader/src/main.rs"] --> WinAPI["Windows API"]
QuickJS["QuickJS 引擎<br/>runtime/build.rs"] --> CC["cc crate"]
```

**图表来源**
- [runtime/Cargo.toml:10-30](file://runtime/Cargo.toml#L10-L30)
- [runtime/Cargo.toml:28-30](file://runtime/Cargo.toml#L28-L30)
- [Cargo.toml:22-46](file://Cargo.toml#L22-L46)
- [loader/src/main.rs:141-149](file://loader/src/main.rs#L141-L149)
- [runtime/build.rs:32-37](file://runtime/build.rs#L32-L37)

**章节来源**
- [runtime/Cargo.toml:1-39](file://runtime/Cargo.toml#L1-L39)
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [loader/src/main.rs:130-200](file://loader/src/main.rs#L130-L200)

## 性能考虑
- NaN-boxing 的优势
  - 单寄存器承载值与类型，减少内存占用与提升访存效率
  - 严格相等在多数情况下可通过位比较快速完成
- 数组与对象的池化
  - 通过索引寻址避免频繁分配，降低 GC 压力
- 重定位策略
  - 优先使用 REL32，减少跨段跳转开销
  - 外部符号解析缓存，避免重复查询
- 编译性能
  - 分阶段统计解析与代码生成耗时，便于定位瓶颈
  - 源映射摘要有助于调试与性能分析
- **新增**：QuickJS 性能影响
  - 执行速度：相比原生实现约 10-100x 慢
  - 内存开销：增加约 200KB 运行时体积
  - 值转换：存在性能开销，但提供更好的包兼容性
- **新增**：外部 crate 优势
  - 性能提升：使用成熟的第三方库替代自定义实现
  - 稳定性增强：经过广泛测试的库更加可靠
  - 维护成本降低：减少自定义代码维护工作

## 故障排查指南
- 编译错误
  - 使用 tsn_compile 返回的错误信息与行列号定位问题
  - 错误上下文字符串可用于快速复现
- 运行时符号未解析
  - 确认运行时插件已加载且导出所需 js_* 符号
  - 检查重定位表中的目标名是否匹配
- 内存分配失败
  - VirtualAlloc 返回空指针时检查权限与大小
- 性能异常
  - 开启详细日志，观察各阶段耗时与内存使用
  - 关注重定位成功率与失败原因
- **新增**：QuickJS 相关问题
  - 检查 quickjs feature 是否正确启用
  - 验证 QuickJS 源码目录是否存在
  - 确认 js_engine 配置正确
- **新增**：外部 crate 问题
  - 检查 Cargo.toml 中依赖版本冲突
  - 验证外部库的 API 兼容性

**章节来源**
- [src/tsn_ffi.rs:294-340](file://src/tsn_ffi.rs#L294-L340)
- [loader/src/main.rs:632-711](file://loader/src/main.rs#L632-L711)
- [loader/src/main.rs:574-586](file://loader/src/main.rs#L574-L586)
- [runtime/build.rs:6-37](file://runtime/build.rs#L6-L37)

## 结论
ts-native 的运行时系统通过 NaN-boxing 值表示与丰富的运行时函数，结合编译器生成的高效机器码与加载器的动态链接能力，实现了从 TypeScript 到本地可执行代码的完整链路。**新增的 QuickJS 引擎集成**提供了对纯 JavaScript npm 包的回退支持，而**外部 crate 替代自定义实现**进一步提升了性能和稳定性。该系统在保持 JS 语义一致性的同时，提供了良好的性能与可扩展性。

## 附录
- 使用示例与最佳实践
  - 在 TypeScript 中导入运行时模块（如 fs、json）并调用其方法
  - 通过运行时插件暴露的 js_* 函数进行字符串、数组、对象操作
  - 在生产环境中开启日志与性能统计，定期评估编译与执行耗时
  - **新增**：合理配置 js-engine，平衡性能与包兼容性
  - **新增**：利用外部 crate 提升加密、压缩等功能的性能
- 调试技巧
  - 使用 RUST_LOG 控制日志级别
  - 通过源映射与编译报告定位热点模块与函数
  - 在加载器中打印代码预览与重定位详情
  - **新增**：监控 QuickJS 执行性能，识别回退包使用情况
  - **新增**：验证外部 crate 的正确集成与版本兼容性