# 项目管理系统

<cite>
**本文档引用的文件**
- [src/lib.rs](file://src/lib.rs)
- [src/main.rs](file://src/main.rs)
- [src/project.rs](file://src/project.rs)
- [src/project_compiler.rs](file://src/project_compiler.rs)
- [src/dep_graph.rs](file://src/dep_graph.rs)
- [src/swc_transform.rs](file://src/swc_transform.rs)
- [src/codegen.rs](file://src/codegen.rs)
- [src/standalone_gen.rs](file://src/standalone_gen.rs)
- [src/coff.rs](file://src/coff.rs)
- [src/tsn_ffi.rs](file://src/tsn_ffi.rs)
- [runtime/build.rs](file://runtime/build.rs)
- [runtime/src/lib.rs](file://runtime/src/lib.rs)
- [Cargo.toml](file://Cargo.toml)
- [docs/README.md](file://docs/README.md)
- [test_multi_entry/src/main.ts](file://test_multi_entry/src/main.ts)
- [test_multi_entry/src/utils/math.ts](file://test_multi_entry/src/utils/math.ts)
- [test_multi_entry/src/lib/core.ts](file://test_multi_entry/src/lib/core.ts)
- [tsnp/console/ts-native.toml](file://tsnp/console/ts-native.toml)
</cite>

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

## 简介
本文件面向 ts-native 的项目管理系统，系统性阐述以下主题：
- 项目结构发现机制：如何扫描目录、识别入口与模块、解析导入路径
- 模块依赖分析：如何解析 TS/JS/MJS 源码、构建依赖图、计算编译层级与拓扑顺序
- 编译顺序确定算法：Kahn 拓扑排序、层级计算、闭包收集
- 依赖图构建过程：节点构造、反向依赖、导出/导入解析
- 拓扑排序实现与循环依赖检测：队列推进、入度统计、异常处理
- 多模块项目的编译协调与资源管理：对象文件合并、符号重命名、重定位应用
- 项目配置文件处理：ts-native.toml 配置解析、shim 依赖跟踪、npm 包扫描、Native Addon 配置解析、**新增：QuickJS 引擎配置与 fallback 包管理**
- 模块解析规则：相对路径、用户模块优先级、shim > npm 包 > native addon > 内置模块的完整优先级链
- 编译报告生成：阶段耗时、内存估算、模块统计、入口产物
- 最佳实践与性能优化：缓存、并行、对齐、符号命名空间
- 大规模项目处理方案：分层编译、增量构建、符号去重

## 项目结构
仓库采用 Rust crate 结构，核心库与命令行工具并存；同时提供独立的多入口测试样例，便于演示复杂依赖关系。

```mermaid
graph TB
subgraph "Rust 包"
Cargo[Cargo.toml]
Lib[lib.rs<br/>公共模块导出]
Main[main.rs<br/>CLI 入口]
Project[project.rs<br/>项目发现与解析]
DepGraph[dep_graph.rs<br/>依赖图构建]
Compiler[project_compiler.rs<br/>项目编译器]
Transform[swc_transform.rs<br/>TS 解析与 HIR]
CodeGen[codegen.rs<br/>Cranelift 代码生成]
Standalone[standalone_gen.rs<br/>独立可执行生成]
Coff[coff.rs<br/>COFF 解析]
FFI[tsn_ffi.rs<br/>DLL 导出]
Runtime[runtime/src/lib.rs<br/>运行时系统]
end
subgraph "测试样例"
TestMain[test_multi_entry/src/main.ts]
TestUtils[test_multi_entry/src/utils/math.ts]
TestCore[test_multi_entry/src/lib/core.ts]
end
Cargo --> Lib
Cargo --> Main
Main --> Transform
Main --> CodeGen
Lib --> Project
Lib --> DepGraph
Lib --> Compiler
Lib --> Transform
Lib --> CodeGen
Lib --> Standalone
Lib --> Coff
Lib --> FFI
Compiler --> DepGraph
Compiler --> Project
Compiler --> Standalone
DepGraph --> Project
DepGraph --> Transform
CodeGen --> Transform
Standalone --> Coff
Runtime --> CodeGen
TestMain --> TestUtils
TestMain --> TestCore
TestUtils --> TestCore
```

**图表来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/project.rs:1-1439](file://src/project.rs#L1-L1439)
- [src/dep_graph.rs:1-257](file://src/dep_graph.rs#L1-L257)
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)
- [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/standalone_gen.rs:1-637](file://src/standalone_gen.rs#L1-L637)
- [src/coff.rs:1-388](file://src/coff.rs#L1-L388)
- [src/tsn_ffi.rs:1-341](file://src/tsn_ffi.rs#L1-L341)
- [runtime/src/lib.rs:1-1679](file://runtime/src/lib.rs#L1-L1679)
- [test_multi_entry/src/main.ts:1-15](file://test_multi_entry/src/main.ts#L1-L15)
- [test_multi_entry/src/utils/math.ts:1-19](file://test_multi_entry/src/utils/math.ts#L1-L19)
- [test_multi_entry/src/lib/core.ts:1-14](file://test_multi_entry/src/lib/core.ts#L1-L14)

**章节来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)
- [src/lib.rs:1-17](file://src/lib.rs#L1-L17)
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [docs/README.md:1-9](file://docs/README.md#L1-L9)

## 核心组件
- 项目发现与解析（Project）：扫描目录、识别入口、解析导入路径、加载文件内容
- 依赖图构建（DepGraph）：解析导出/导入、构建节点与边、拓扑排序、层级计算、闭包收集
- 项目编译器（ProjectCompiler）：协调编译流程、生成对象文件、合并为独立可执行、生成编译报告
- TypeScript 解析（swc_transform）：将 TS/JS/MJS 源码解析为 HIR，提取函数、导入绑定等
- 代码生成（codegen）：基于 HIR 生成 Cranelift IR，并输出 COFF/TSN 对象数据
- 独立可执行生成（standalone_gen）：序列化模块数据、生成 .tsnobj、解析重定位
- COFF 解析（coff）：解析标准 COFF 对象文件，提取节、符号、重定位
- FFI/DLL 接口（tsn_ffi）：导出 DLL 函数供外部加载器调用
- CLI 入口（main.rs）：命令行参数解析、单文件编译流程
- **新增：运行时系统（runtime）**：支持 QuickJS 引擎集成与 JavaScript 执行

**章节来源**
- [src/project.rs:1-1439](file://src/project.rs#L1-L1439)
- [src/dep_graph.rs:1-257](file://src/dep_graph.rs#L1-L257)
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)
- [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/standalone_gen.rs:1-637](file://src/standalone_gen.rs#L1-L637)
- [src/coff.rs:1-388](file://src/coff.rs#L1-L388)
- [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:1-1679](file://runtime/src/lib.rs#L1-L1679)

## 架构概览
整体编译流程分为"发现与解析"、"依赖分析"、"编译与合并"、"产物生成与报告"四个阶段，贯穿 CLI 与库两种使用方式。**新增：QuickJS 引擎集成支持 JavaScript 代码执行与 fallback 包管理**。

```mermaid
sequenceDiagram
participant CLI as "CLI(main.rs)"
participant Project as "Project"
participant Dep as "DepGraph"
participant Compiler as "ProjectCompiler"
participant Transform as "swc_transform"
participant CodeGen as "CodeGen"
participant Runtime as "Runtime"
participant Standalone as "standalone_gen"
CLI->>Transform : 解析输入 TS/JS/MJS 源码
Transform-->>CLI : HIR
CLI->>CodeGen : 生成 COFF
CodeGen-->>CLI : COFF 字节流
CLI-->>CLI : 写入 .obj 并提示执行 tsn-loader
Note over CLI,CodeGen : 单文件编译模式
Compiler->>Project : from_dir() 扫描与入口识别
Compiler->>Dep : from_project() 构建依赖图
Dep-->>Compiler : compile_order, entry_closures
loop 按拓扑顺序
Compiler->>Transform : 解析模块 HIR
Compiler->>CodeGen : 生成 .obj
CodeGen-->>Compiler : COFF 字节流
end
Compiler->>Standalone : 合并对象、重命名符号、应用重定位
Standalone-->>Compiler : .tsnobj + .exe
Compiler-->>Compiler : 生成编译报告
Note over Runtime,CodeGen : QuickJS 引擎集成
Runtime->>CodeGen : 配置 fallback 包列表
CodeGen-->>Runtime : 执行 JavaScript 代码
```

**图表来源**
- [src/main.rs:1-79](file://src/main.rs#L1-L79)
- [src/project.rs:101-197](file://src/project.rs#L101-L197)
- [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:542-552](file://src/codegen.rs#L542-L552)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [runtime/src/lib.rs:1554-1679](file://runtime/src/lib.rs#L1554-L1679)

## 详细组件分析

### 项目结构发现与模块解析（Project）
- 扫描策略：优先读取 ts-native.toml（shim 配置），然后尝试读取 tsn-project.toml，最后默认扫描 src 目录；自动识别入口（src 下直接子文件或根目录 .ts/.js/.mjs 文件，或默认 main.ts）
- 配置文件处理：
  - ts-native.toml：解析 [shims]、[native_addons] 和 **[js-engine]** 配置，支持注释和空行
  - tsn-project.toml：预留配置文件支持（当前暂不解析）
- 模块名规范化：去除 src/ 前缀与 .ts/.js/.mjs 扩展，斜杠统一为路径分隔符
- 导入解析规则：
  - 相对路径：基于 from 的相对路径解析，支持 ./ 与 ../，规范化后匹配 .ts/.js/.mjs 或 index.ts/index.js/index.mjs
  - 非相对路径：优先匹配项目内用户模块（src/<module>.ts/.js/.mjs 或 src/<module>/index.ts/index.js/index.mjs），若不存在则检查 shim 配置，再检查 npm 包，最后视为内置模块（返回 None）
  - 用户模块优先级：当存在同名内置模块（如 "fs"）时，import "fs" 会被解析为用户模块，给出提示
  - npm 包支持：自动识别 node_modules 下的包名，支持作用域包（@types/node）
  - Native Addon 支持：通过 [native_addons] 配置识别 addon 包，支持 DLL 加载和函数映射
  - CommonJS require：通过 Var 包装的 ImportBinding 识别 require("mod") 语法
- **新增：QuickJS 引擎配置**：通过 [js-engine] 配置启用 QuickJS 引擎，支持 fallback 包列表管理
- 文件内容延迟加载：避免一次性读取全部文件，按需加载以节省内存

```mermaid
flowchart TD
Start(["开始: from_dir(root)"]) --> CheckTsNative["检查 ts-native.toml<br/>解析 [shims]/[native_addons]/[js-engine]"]
CheckTsNative --> CheckTsn["检查 tsn-project.toml"]
CheckTsn --> ScanSrc["扫描 src/ 目录<br/>支持 .ts/.js/.mjs"]
ScanSrc --> IdentifyEntries{"是否显式配置入口?"}
IdentifyEntries --> |是| ExplicitEntries["匹配配置入口并标记"]
IdentifyEntries --> |否| AutoEntries["自动识别入口:<br/>src 直接子文件 + 根目录 .ts/.js/.mjs<br/>默认 main.ts"]
ExplicitEntries --> CollectModules["收集模块文件(非入口)"]
AutoEntries --> CollectModules
CollectModules --> ResolveImports["resolve_import()<br/>相对路径/用户模块优先级/shim/npm包/native addon"]
ResolveImports --> CheckQJS{"检查 QuickJS 配置<br/>enabled/fallback 包"}
CheckQJS --> End(["完成"])
```

**图表来源**
- [src/project.rs:101-197](file://src/project.rs#L101-L197)
- [src/project.rs:201-313](file://src/project.rs#L201-L313)
- [src/project.rs:398-465](file://src/project.rs#L398-L465)
- [src/project.rs:584-592](file://src/project.rs#L584-L592)

**章节来源**
- [src/project.rs:1-1439](file://src/project.rs#L1-L1439)

### 依赖图构建与拓扑排序（DepGraph）
- 节点构造：解析每个模块的导出与导入，记录 deps 与 reverse_deps
- 导出/导入解析：通过 swc_transform 的 HIR 提取导出函数名与导入模块标识，支持 CommonJS require 语法
- 反向依赖：遍历 deps，填充 reverse_deps，用于层级计算
- shim 依赖处理：识别 __shim__/ 前缀的 shim 路径，记录但不加入 deps（不需要编译）
- 拓扑排序（Kahn 算法）：基于入度统计，入度为 0 的模块先入队，逐步弹出并减少邻居入度
- 循环依赖检测：若最终结果长度小于节点数，判定存在环
- 层级计算：叶子模块 level=0，其他模块 level=max(children_levels)+1
- 闭包计算：从入口出发 DFS/BFS 收集其依赖闭包（包含自身）

```mermaid
flowchart TD
BuildStart(["构建 DepGraph"]) --> ParseAll["解析所有模块 HIR<br/>提取 exports/imports<br/>支持 CommonJS require"]
ParseAll --> BuildNodes["构造 ModuleNode<br/>deps/reverse_deps/is_shim"]
BuildNodes --> CheckShim{"检查 shim 依赖"}
CheckShim --> |是| RecordShim["记录 shim 依赖<br/>不加入 deps"]
CheckShim --> |否| AddDeps["加入 deps 边"]
RecordShim --> AddDeps
AddDeps --> KahnInit["初始化入度/邻接表"]
KahnInit --> KahnLoop{"队列非空?"}
KahnLoop --> |是| Pop["弹出入度为0的节点"]
Pop --> PushOrder["加入 compile_order"]
PushOrder --> Decr["对其邻居入度-1"]
Decr --> KahnLoop
KahnLoop --> |否| CheckLen{"结果长度==节点数?"}
CheckLen --> |否| Error["抛出循环依赖错误"]
CheckLen --> |是| LevelCalc["计算每个节点 level"]
LevelCalc --> Closure["计算每个入口的依赖闭包"]
Closure --> BuildEnd(["完成"])
```

**图表来源**
- [src/dep_graph.rs:43-132](file://src/dep_graph.rs#L43-L132)
- [src/dep_graph.rs:167-210](file://src/dep_graph.rs#L167-L210)
- [src/dep_graph.rs:212-240](file://src/dep_graph.rs#L212-L240)

**章节来源**
- [src/dep_graph.rs:1-257](file://src/dep_graph.rs#L1-L257)

### 项目编译器与编译协调（ProjectCompiler）
- 编译阶段划分：
  - 模块编译阶段：按拓扑顺序编译所有模块，生成 .obj；统计函数声明/编译数、代码/数据段大小、符号与重定位数量
  - 独立可执行生成阶段：为每个入口收集闭包模块，合并为 ModuleData，应用符号重命名与重定位，生成 .tsnobj 与 .exe
  - 报告生成阶段：汇总阶段耗时、内存估算、模块统计、入口产物路径
- 符号重命名与命名空间隔离：非入口模块的符号前缀化，避免符号冲突
- 重定位应用：区分内部符号与外部 js_* 符号，分别定位至已分配的代码/数据段或运行时 DLL
- 运行时依赖：自动复制 tsn_runtime.dll 至输出目录，或提示缺失
- **新增：QuickJS 集成支持**：通过 CodeGen 的 with_qjs_fallback 方法传递 fallback 包配置

```mermaid
sequenceDiagram
participant PC as "ProjectCompiler"
participant DG as "DepGraph"
participant PJ as "Project"
participant CG as "CodeGen"
participant RT as "Runtime"
participant SG as "standalone_gen"
PC->>PJ : from_dir()
PJ-->>PC : Project
PC->>DG : from_project(PJ)
DG-->>PC : compile_order, entry_closures
loop 模块编译
PC->>CG : compile_module(path)
CG-->>PC : COFF 字节流
end
loop 入口产物
PC->>SG : build_standalone_executable(entry)
SG-->>PC : .tsnobj + .exe
end
PC-->>PC : 生成编译报告
Note over PC,RT : QuickJS 集成
PC->>CG : with_qjs_fallback(fallback_list)
CG-->>PC : 配置完成
```

**图表来源**
- [src/project_compiler.rs:205-332](file://src/project_compiler.rs#L205-L332)
- [src/project_compiler.rs:334-382](file://src/project_compiler.rs#L334-L382)
- [src/project_compiler.rs:384-567](file://src/project_compiler.rs#L384-L567)
- [src/codegen.rs:542-552](file://src/codegen.rs#L542-L552)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)

**章节来源**
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)

### 类型与数据结构（核心模型）
```mermaid
classDiagram
class Project {
+root : PathBuf
+config : ProjectConfig
+files : HashMap<PathBuf, SourceFile>
+entries : Vec<PathBuf>
+modules : Vec<PathBuf>
+from_dir(root)
+resolve_import(from, import_path)
+load_content(path)
+is_shim_path(path)
+shim_package_name(path)
+is_native_addon(package_name)
+get_addon_dll(package_name)
+get_addon_functions(package_name)
+is_qjs_fallback(package_name)
+get_qjs_fallback_packages()
}
class ProjectConfig {
+entries : Vec<String>
+src_dir : String
+out_dir : String
+shims : HashMap<String, String>
+npm_packages : HashMap<String, PathBuf>
+native_addons : HashMap<String, NativeAddonConfig>
+js_engine : JsEngineConfig
}
class JsEngineConfig {
+enabled : bool
+fallback : Vec<String>
}
class NativeAddonConfig {
+dll : String
+functions : HashMap<String, String>
}
class SourceFile {
+path : PathBuf
+module_name : String
+is_entry : bool
+content : Option<String>
+is_npm_package : bool
}
class DepGraph {
+nodes : HashMap<PathBuf, ModuleNode>
+entry_closures : HashMap<PathBuf, Vec<PathBuf>>
+compile_order : Vec<PathBuf>
+from_project(project)
+get_compile_order()
+get_entry_modules(entry)
}
class ModuleNode {
+path : PathBuf
+module_name : String
+exports : HashSet<String>
+imports : HashMap<PathBuf, Vec<String>>
+deps : Vec<PathBuf>
+reverse_deps : Vec<PathBuf>
+level : usize
+is_entry : bool
+is_shim : bool
}
class ProjectCompiler {
+project : Project
+dep_graph : DepGraph
+compiled_objects : HashMap<PathBuf, Vec<u8>>
+module_symbols : HashMap<String, String>
+report : CompileReport
+compile_project()
+compile_module(path)
+build_standalone_executable(entry)
}
ProjectCompiler --> Project : "使用"
ProjectCompiler --> DepGraph : "使用"
DepGraph --> Project : "依赖"
```

**图表来源**
- [src/project.rs:18-46](file://src/project.rs#L18-L46)
- [src/dep_graph.rs:32-41](file://src/dep_graph.rs#L32-L41)
- [src/project_compiler.rs:189-203](file://src/project_compiler.rs#L189-L203)

**章节来源**
- [src/project.rs:1-1439](file://src/project.rs#L1-L1439)
- [src/dep_graph.rs:1-257](file://src/dep_graph.rs#L1-L257)
- [src/project_compiler.rs:1-728](file://src/project_compiler.rs#L1-L728)

### 多模块项目编译示例（test_multi_entry）
- 依赖关系：main.ts 依赖 utils/math.ts 与 lib/core.ts；utils/math.ts 依赖 lib/core.ts；lib/core.ts 为叶子模块
- 编译顺序：lib/core.ts（level=0）→ utils/math.ts（level=1）→ main.ts（level=2）
- 入口闭包：每个入口仅包含其依赖链上的模块

```mermaid
graph LR
Core["lib/core.ts"] --> Math["utils/math.ts"]
Math --> Main["main.ts"]
```

**图表来源**
- [test_multi_entry/src/main.ts:1-15](file://test_multi_entry/src/main.ts#L1-L15)
- [test_multi_entry/src/utils/math.ts:1-19](file://test_multi_entry/src/utils/math.ts#L1-L19)
- [test_multi_entry/src/lib/core.ts:1-14](file://test_multi_entry/src/lib/core.ts#L1-L14)

**章节来源**
- [test_multi_entry/src/main.ts:1-15](file://test_multi_entry/src/main.ts#L1-L15)
- [test_multi_entry/src/utils/math.ts:1-19](file://test_multi_entry/src/utils/math.ts#L1-L19)
- [test_multi_entry/src/lib/core.ts:1-14](file://test_multi_entry/src/lib/core.ts#L1-L14)

### ts-native.toml 配置解析与 shim 依赖跟踪
- 配置文件解析：支持注释（# 开头）、空行跳过，解析 [shims]、[native_addons] 和 **[js-engine]** 配置
- shim 依赖处理：配置的包名映射到 shim 模块名，生成 __shim__/ 前缀路径
- native addon 支port：解析 DLL 文件名和函数映射，支持多 addon 配置
- **新增：js-engine 配置**：解析 enabled 标志和 fallback 包列表，支持数组格式解析
- 配置示例：参考 tsnp/console/ts-native.toml 中的 functions 配置

**章节来源**
- [src/project.rs:201-313](file://src/project.rs#L201-L313)
- [src/project.rs:584-592](file://src/project.rs#L584-L592)
- [src/dep_graph.rs:63-74](file://src/dep_graph.rs#L63-L74)
- [src/codegen.rs:542-552](file://src/codegen.rs#L542-L552)
- [tsnp/console/ts-native.toml:1-16](file://tsnp/console/ts-native.toml#L1-L16)

### npm 包扫描与 CommonJS require 识别
- npm 包模块名提取：自动识别 node_modules 下的包名，支持作用域包（@types/node）
- CommonJS require 支持：通过 Var 包装的 ImportBinding 识别 require("mod") 语法
- 文件扩展名支持：扫描 .ts/.js/.mjs 文件，自动识别不同语言的模块
- 包路径解析：从 from 文件向上查找 node_modules/ 目录，解析包入口文件

**章节来源**
- [src/project.rs:467-512](file://src/project.rs#L467-L512)
- [src/project.rs:584-592](file://src/project.rs#L584-L592)
- [src/dep_graph.rs:169-181](file://src/dep_graph.rs#L169-L181)

### Native Addon FFI Bridge 功能
- NativeAddonConfig 结构：包含 DLL 文件名和函数映射，支持多 addon 配置
- 配置解析：支持 [native_addons.<addon>] 和 [native_addons.<addon>.functions] 两级配置
- DLL 加载：支持从可执行文件同目录和当前工作目录加载 addon DLL
- 函数映射：通过 addon_ 前缀的外部符号实现 TS 函数到 DLL 导出函数的桥接
- 重定位支持：在独立可执行生成阶段解析 addon 符号，支持动态库函数调用

**章节来源**
- [src/project.rs:8-16](file://src/project.rs#L8-L16)
- [src/project.rs:569-582](file://src/project.rs#L569-L582)
- [src/codegen.rs:531-540](file://src/codegen.rs#L531-L540)
- [src/codegen.rs:599-609](file://src/codegen.rs#L599-L609)
- [src/standalone_gen.rs:136-168](file://src/standalone_gen.rs#L136-L168)
- [src/standalone_gen.rs:244-260](file://src/standalone_gen.rs#L244-L260)

### **新增：QuickJS 引擎配置与集成**
- **JsEngineConfig 结构**：新增 JsEngineConfig 结构体，包含 enabled 标志和 fallback 包列表
- **配置解析**：在 parse_ts_native_toml 中解析 [js-engine] section，支持 enabled 和 fallback 数组
- **fallback 包管理**：通过 is_qjs_fallback 和 get_qjs_fallback_packages 方法管理 QuickJS fallback 包
- **运行时集成**：通过 CodeGen 的 with_qjs_fallback 方法传递配置到运行时系统
- **条件编译**：QuickJS 功能通过 cargo feature 条件编译，未启用时返回 undefined/false

**章节来源**
- [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:584-592](file://src/project.rs#L584-L592)
- [src/codegen.rs:542-552](file://src/codegen.rs#L542-L552)
- [runtime/src/lib.rs:1554-1679](file://runtime/src/lib.rs#L1554-L1679)

## 依赖分析
- 外部依赖：SWC（解析 TS/JS/MJS）、Cranelift（IR 与代码生成）、object（COFF 解析）、anyhow/env_logger/clap 等
- 功能特性开关：coff、native-linker
- 二进制产物：CLI 可执行（ts-native）、可选 native-linker、库（cdylib/rlib）
- **新增：QuickJS 运行时依赖**：通过 runtime crate 提供 JavaScript 引擎支持

```mermaid
graph TB
Cargo[Cargo.toml] --> SWC["swc_* (解析)"]
Cargo --> CL["cranelift-* (IR/CodeGen)"]
Cargo --> OBJ["object (COFF)"]
Cargo --> ANY["anyhow/env_logger/clap"]
Cargo --> Features["features: coff, native-linker"]
Cargo --> Runtime["runtime crate<br/>QuickJS 引擎"]
```

**图表来源**
- [Cargo.toml:26-61](file://Cargo.toml#L26-L61)
- [runtime/build.rs:1-37](file://runtime/build.rs#L1-L37)

**章节来源**
- [Cargo.toml:1-61](file://Cargo.toml#L1-L61)

## 性能考虑
- 内存估算：按平台 API 获取进程驻留集大小（Windows 使用 GetProcessMemoryInfo，其他平台读取 /proc/self/status），用于编译报告
- 对齐与布局：合并模块数据时按 16 字节对齐，减少重定位开销
- 符号去重与命名空间：非入口模块符号前缀化，避免重复符号导致的链接问题
- 统计指标：函数声明/编译数、代码/数据段大小、重定位数量、阶段耗时与内存使用
- 建议：在大型项目中启用增量编译（可基于文件变更时间）、缓存 HIR 与中间结果、并行编译不同模块（注意符号表一致性）
- **新增：QuickJS 性能优化**：通过 fallback 包列表减少不必要的引擎切换开销

## 故障排查指南
- 循环依赖：拓扑排序阶段若结果长度不足，抛出循环依赖错误；建议重构模块拆分或引入适配层
- 导入解析失败：相对路径解析失败或用户模块优先级导致的解析偏差；检查路径规范与 src 目录结构
- shim 配置错误：ts-native.toml 中的 [shims] 配置格式不正确；检查 key-value 格式和引号
- native addon 未找到：配置的 DLL 文件不存在或函数映射不正确；确认文件路径和导出函数名
- native addon DLL 加载失败：检查 DLL 文件位置和依赖项；确认可执行文件同目录和工作目录的搜索顺序
- CommonJS require 识别失败：require 语法不被正确识别；检查语法格式
- 重定位失败：外部 js_* 符号未解析或内部符号未找到；确认 tsn_runtime.dll 存在且路径正确
- 运行时缺失：找不到 tsn_runtime.dll；确保复制到输出目录或在 PATH 中
- COFF 解析错误：COFF 文件损坏或格式不支持；检查生成流程与工具链版本
- **新增：QuickJS 集成问题**：检查 js-engine.enabled 配置、fallback 包列表格式、QuickJS 构建状态

**章节来源**
- [src/dep_graph.rs:205-207](file://src/dep_graph.rs#L205-L207)
- [src/project_compiler.rs:569-660](file://src/project_compiler.rs#L569-L660)
- [src/standalone_gen.rs:390-487](file://src/standalone_gen.rs#L390-L487)
- [src/coff.rs:72-231](file://src/coff.rs#L72-L231)

## 结论
ts-native 的项目管理系统以清晰的模块化设计实现了从项目发现、依赖分析到编译与产物生成的完整闭环。通过 SWC 解析与 Cranelift 代码生成，结合独立可执行生成与运行时 DLL 的协作，既保证了编译质量，又提供了良好的运行时体验。**新增的 QuickJS 引擎配置与 fallback 包管理功能**进一步增强了系统的灵活性和兼容性，允许开发者选择性地将某些包交给 JavaScript 引擎执行，从而平衡编译性能与运行时功能。通过用户模块 > shim > npm 包 > native addon > 内置模块的完整优先级链，系统能够灵活处理各种模块解析场景。建议在大规模项目中配合增量编译、符号命名空间与并行化策略，持续优化编译性能与稳定性。

## 附录
- 项目配置文件：ts-native.toml（shim 配置解析）、tsn-project.toml（预留配置）
- CLI 使用：ts-native <input.ts> [-o output.obj]；输出 .obj 并提示使用 tsn-loader
- FFI/DLL：导出 tsn_compile、tsn_free_result、tsn_version 等函数，支持 COFF 导出（coff 特性）
- 支持的文件类型：.ts（TypeScript）、.js（JavaScript）、.mjs（ES 模块）
- shim 配置格式：[shims] section 中的 key-value 映射
- native addon 配置格式：[native_addons.<addon>] 和 [native_addons.<addon>.functions] sections
- **新增：js-engine 配置格式**：[js-engine] section 中的 enabled 标志和 fallback 数组
- Native Addon FFI 桥接：通过 addon_ 前缀的外部符号实现 TS 函数到 DLL 导出函数的映射
- **新增：QuickJS 引擎集成**：通过 runtime crate 提供 JavaScript 执行能力，支持条件编译与 fallback 包管理

**章节来源**
- [src/main.rs:7-78](file://src/main.rs#L7-L78)
- [src/tsn_ffi.rs:60-170](file://src/tsn_ffi.rs#L60-L170)
- [src/tsn_ffi.rs:172-292](file://src/tsn_ffi.rs#L172-L292)
- [src/project.rs:201-313](file://src/project.rs#L201-L313)
- [src/project.rs:467-512](file://src/project.rs#L467-L512)
- [src/dep_graph.rs:63-74](file://src/dep_graph.rs#L63-L74)
- [src/codegen.rs:542-552](file://src/codegen.rs#L542-L552)
- [runtime/src/lib.rs:1554-1679](file://runtime/src/lib.rs#L1554-L1679)