依赖与进程拓扑

ttsc 在运行时是一组互相 spawn 的进程,靠环境变量握手、CLI 参数和 JSON 信封连接。本页画出谁 spawn 谁、二进制怎么解析、环境变量怎么传,让你在调试"进程没起来 / 找不到二进制 / 插件没生效"时知道去哪看。

进程 spawn 拓扑

Loading graph...

上图用 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 这类需要原生宿主的命令通过 delegateToNativerunTtsc.ts:244)走它;找不到时报清晰错误,提示设 TTSC_BINARY 或重装可选依赖。

打包的 Go 编译器(resolveGoCompiler

buildSourcePlugin.ts::resolveGoCompilersrc/plugin/internal/buildSourcePlugin.ts:979)按以下顺序找 go

  1. TTSC_GO_BINARY 环境变量;
  2. @ttsc/{platform}-{arch}/bin/go/bin/go(打包的 Go SDK,主路径);
  3. 相对路径回退(../../../../ttsc-{platform}-{arch}/bin/go/...native/go/...~/go-sdk/go/...);
  4. 最后退到系统 go

关键设计:ttsc 默认用自带的 Go SDK 编译插件,不依赖用户机器装没装 Go。这让 npx ttsc 在干净环境里也能构建插件。

环境变量握手汇总

变量谁设谁读作用
TTSC_NODE_BINARYmergeEnv / nativePluginEnv旁车回调 Node 不必搜 PATH
TTSC_TSGO_BINARYnativePluginEnv / runTtsx旁车 / ttsx 子进程tsgo 位置
TTSC_TTSX_BINARYnativePluginEnv / withPluginLoaderEnv插件加载器加载 .ts 描述符
TTSC_LINKED_PLUGINS_JSONnativePluginEnv(transform 阶段)driver.loadLinkedPluginState链接插件 manifest
TTSC_LSP_PLUGINS_JSONJS launchercmd/ttscserverNativePluginSourceLSP 插件 manifest
TTSC_CACHE_DIR用户 / --cache-dirbuildSourcePlugin / 清理逻辑覆盖缓存根
TTSC_GO_BINARY用户resolveGoCompiler覆盖 Go 编译器
TTSC_BINARY用户resolveBinary覆盖平台 helper
TTSC_PLUGIN_DESCRIPTOR_LOAD加载器描述符加载 shim全图禁用插件,防自托管死锁
TTSX_RUNTIME_MANIFESTrunTtsx运行时钩子指向已构建入口项目 emit
XDG_CACHE_HOME / LOCALAPPDATAOSresolveUserCacheRoot全局缓存根定位

nativePluginEnv 的实现在两处镜像:runBuild.ts:126(构建路径)与 transformProjectInMemory.ts:297(转换路径),都遵循"已存在则不覆盖"(process.env.X ?? default)。

npm 包依赖图

  • ttsc 把七个平台包列为 optionalDependenciespackages/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 注释)。

ttsc → @ttsc/banner → @ttsc/lint → @ttsc/unplugin → @ttsc/metro
     → @ttsc/vscode → 平台包 → @ttsc/graph → lint-contributor-demo

调试入口

症状先看
"TypeScript-Go executable not found"resolveTsgoTTSC_TSGO_BINARY、平台包是否装上
"platform-specific helper binary not found"resolveBinary@ttsc/{platform}-{arch} 可选依赖
插件没被构建 / go build 失败buildSourcePluginresolveGoCompiler、缓存目录、TTSC_GO_BINARY
插件构建成功但没生效loadProjectPlugins 的发现逻辑、--plugins-json、阶段排序
链接插件没注册TTSC_LINKED_PLUGINS_JSONdriver.RegisterPlugin 顺序
LSP 插件诊断没出现TTSC_LSP_PLUGINS_JSONNativePluginSource、脏文档守卫

接下来