依赖与进程拓扑
ttsc 在运行时是一组互相 spawn 的进程,靠环境变量握手、CLI 参数和 JSON 信封连接。本页画出谁 spawn 谁、二进制怎么解析、环境变量怎么传,让你在调试"进程没起来 / 找不到二进制 / 插件没生效"时知道去哪看。
进程 spawn 拓扑
上图用 Graphviz(
```viz围栏),由文档站的rspress-plugin-viz渲染。
二进制解析顺序
ttsc 要在运行时找到三类原生产物:tsgo 二进制、ttsc 平台 helper、打包的 Go 编译器。
tsgo 二进制(resolveTsgo)
src/compiler/internal/resolveTsgo.ts 负责定位 tsgo。它优先用显式 --binary / TTSC_TSGO_BINARY,否则从项目的 node_modules 解析 @typescript/native-preview 风格的平台包。LSP 路径下,ttscserver 通过 --tsgo flag 或 TTSC_TSGO_BINARY 拿到它(cmd/ttscserver/main.go:118)。
ttsc 平台 helper(resolveBinary)
src/compiler/internal/resolveBinary.ts 解析 @ttsc/{platform}-{arch} 包里的原生 helper。ttsc demo 这类需要原生宿主的命令通过 delegateToNative(runTtsc.ts:244)走它;找不到时报清晰错误,提示设 TTSC_BINARY 或重装可选依赖。
打包的 Go 编译器(resolveGoCompiler)
buildSourcePlugin.ts::resolveGoCompiler(src/plugin/internal/buildSourcePlugin.ts:979)按以下顺序找 go:
TTSC_GO_BINARY环境变量;@ttsc/{platform}-{arch}/bin/go/bin/go(打包的 Go SDK,主路径);- 相对路径回退(
../../../../ttsc-{platform}-{arch}/bin/go/...、native/go/...、~/go-sdk/go/...); - 最后退到系统
go。
关键设计:ttsc 默认用自带的 Go SDK 编译插件,不依赖用户机器装没装 Go。这让 npx ttsc 在干净环境里也能构建插件。
环境变量握手汇总
nativePluginEnv 的实现在两处镜像:runBuild.ts:126(构建路径)与 transformProjectInMemory.ts:297(转换路径),都遵循"已存在则不覆盖"(process.env.X ?? default)。
npm 包依赖图
ttsc把七个平台包列为optionalDependencies(packages/ttsc/package.json),按os/cpu自动安装当前平台那一个。@ttsc/factory是独立发布库,零依赖,工作区里目前没有别的包依赖它(见.codex/skills/project/SKILL.md)。website依赖@ttsc/playground与@ttsc/wasm(workspace),用 React 18 + Nextra,与本 Wiki 的 Rspress 站点完全独立。
构建顺序约束
scripts/build-current.cjs 固定了构建顺序,其中一个约束值得记:平台包(携带原生 ttsc 编译器二进制)必须在 @ttsc/graph 之前构建,因为 graph 的构建会跑 ttsc(带 typia 插件),需要那个二进制在场(scripts/build-current.cjs:19 注释)。