编译器语言运行时开发工具CLI【免费下载链接】scriptcTypeScript-to-Native Compiler项目地址https://gitcode.com/GitHub_Trending/sc/scriptc点击查看免费下载导读scriptcTypeScript-to-Native Compiler为真实世界的 Node/TypeScript 项目提供了一条关键的「采纳路径」adoption path当目标项目的node_modules中存在types/node时编译器会让项目自己的 Node 类型声明接管全局类型表面而不是继续使用内置的降级fallback声明。本文以仓库中的 node-types fixture 为骨架完整讲解这条路径的三个核心环节——依赖版本锁定、类型来源切换与 provenance 识别、以及「声明但未降级」表面的 SC2020 栅栏fence机制并逐项结合 编译源码、诊断定义 与 harness 测试 验证其真实行为。读完本文你将掌握如何在有types/node与没有types/node的项目之间理解 scriptc 的类型表面差异如何识别哪些 Node API 会被静态降级、哪些会被拒绝编译以及如何用该机制定位真实项目中的兼容性问题。一、fixture 的定位为真实世界项目准备的测试样本在 tests/fixtures/node-types/ 目录下存在一个刻意与其余 fixture 不同的项目它的node_modules中真实安装了types/node从而模拟一个真实的 Node/TypeScript 项目在 scriptc 下编译时的完整形态。这正是 README 中所说的「the adoption path for real-world Node/TypeScript projects」——大多数现有 fixture 与整个语料库corpus都不带types/node依赖的是 scriptc 内置的降级声明而本 fixture 专门验证另一条路线类型表面完全由项目自己的types/node提供。fixture 的结构如下argv-env.ts— 验证受支持的process表面argv/env在types/node类型化下的静态降级fenced.ts— 验证types/node声明但 scriptc 不降级的表面会以 SC2020 家族栅栏命名types/node而不是编译出一个损坏的二进制也绝不会出现裸的Cannot find name错误source-import/— 验证被导入的 TypeScript 源码可以使用 TypeScript 默认 DOM lib 提供的RequestInfo全局而 scriptc 同时采纳项目的types/node声明其余文件child-execfile.ts、child-stdin.ts、fetch-static.ts、path-os.ts、url-getters.ts、text-codecs.mts等覆盖 spawn 子进程、流捕获、fetch、path/os、URL、编码器等相关子面。二、版本锁定vendored node_modules 是「已提交的测试数据」README 开篇强调了一个关键工程决策vendored内置提交的node_modules是 COMMITTED TEST DATA。也就是说这些依赖不是通过安装步骤动态拉取的而是直接随仓库提交并精确固定版本types/node24.13.3undici-types7.18.2types/node的依赖——它声明了 web 平台全局fetch/Response/AbortSignal/ReadableStream/…对应的依赖声明位于 tests/fixtures/node-types/package.json{ name: node-types-fixture, private: true, devDependencies: { types/node: 24.13.3 } }这种做法的直接收益是类型表面永不随 registry 漂移。因为types/node是一个持续演进的高频发布包如果允许浮动安装那么同一份测试源码在不同时间点会看到不同的类型声明导致「固定的诊断输出」pinned diagnostics不稳定。把 node_modules 提交进仓库后类型表面、以及由此推导出的栅栏诊断快照见 node-types-fenced.txt都与版本绑定harness 测试可以在任何时间、任何环境复现完全一致的结果。三、类型来源切换fallback 声明让位provenance 接管识别3.1 三种 shipped 声明文件的职责划分scriptc 在编译任何程序时都会注入多份声明文件其路径解析全部集中在 packages/compiler/src/frontend/dts-paths.ts函数注入的声明文件参与时机ambientDtsPath()L16-L18核心 ambientcomptime/__island_eval/setTimeout每一个scriptc 构建的程序包括预检preflight程序overridesDtsPath()L25-L27divergence/precision 覆盖JSON.parse(): unknown、pop(): T、Promise executor 形状等仅降级lowering程序预检的 project-world second chance 构建不注入因此项目在自有 tsc 下能通过类型检查时不会被覆盖层人为制造的错误挡住预检fallbackDtsPath()L33-L35降级声明console、process、node:fs仅当目标项目没有types/node时一旦项目自带types/node本文件整体让位3.2 fallback 让位的条件fallbackDtsPath() 的注释 明确了这一逻辑Path of the shipped FALLBACK declarations (console, process, node:fs) — part of the program only when the target project has notypes/node. Withtypes/node, the projects real Node types stand in and this file stands down (its declaration forms would collide).换句话说如果同时注入两份声明console/process/node:fs的声明形式会发生冲突collide因此必须在「shipped fallback」与「项目自己的 types/node」之间二选一。这正是 node-types fixture 与其余 fixture 的本质差异所在其它 fixture 与整个语料库没有types/node保持 shipped fallback 声明行为与之前完全一致本 fixture 则让真实类型声明接管。3.3 provenance降级表如何「认出」types/node 声明的成员类型来源切换之后一个核心问题随之而来argv-env.ts中通过types/node类型化的process.argv、process.env与之前通过 fallback 声明类型化的同名成员为何能降级到同一个静态 libCall答案在 isNodeTypesPath()export function isNodeTypesPath(file: string): boolean { const pkg npmPackageNameOf(file); return pkg types/node || pkg undici-types; }scriptc 的降级lowering表按「成员名 types/node provenance」双重识别凡是来自types/node包或undici-types包后者正是types/node声明的 web 平台全局的来源的类型都被认定为合法的 Node 类型表面。因此fallback 声明让位后相同的成员名仍然降级到相同的 libCalls——只是它们的类型来源从内置声明换成了项目真实的types/node。与此同时provenance 也是 SC2020 家族栅栏的另一半依据凡是这两个包声明但不在降级表内的表面都会被诊断为「typed by types/node but has no scriptc lowering yet」。四、受支持的表面argv/env 在 types/node 下的静态降级4.1 样本程序 argv-env.ts该文件头注释明确了测试意图受支持的 process 表面由 types/node 类型化fallback 声明在本 fixture 中让位argv 与 env 读取降级到与以往相同的静态 libCall测试以参数和环境变量运行二进制并固定输出。const args process.argv; console.log(args.length - 2); for (let i 2; i args.length; i i 1) { console.log(args[i]); } const greeting process.env.SCRIPTC_FIXTURE_GREETING; if (greeting ! undefined) { console.log(greeting); } else { console.log(no greeting); } process.stdout.write(written without newline); console.log( - flushed in order);注意其中的细节设计argv[0]/argv[1]是 Node 形状的 exec/script 路径机器相关所以程序只打印用户参数——从argv[2]开始process.env的读取使用undefined判空而非真值判断以覆盖「环境变量未设置」的分支最后用process.stdout.write做原始字节写入验证在types/node的WriteStream类型下字节写出同样正常降级并与后续console.log的输出顺序一致。4.2 harness 验证编译并运行二进制对应测试位于 tests/harness/project-config.test.tstest(node-types: the supported process surface lowers statically under types/node, async () { const outDir outDirFor(node-types); const result await compile(join(nodeTypesDir, argv-env.ts), { /* ... */ }); expect(result.ok, ...).toBe(true); const { stdout } await execFileAsync(result.binaryPath, [alpha, beta], { env: { ...process.env, SCRIPTC_FIXTURE_GREETING: hi from env }, }); expect(stdout).toBe(2\nalpha\nbeta\nhi from env\nwritten without newline - flushed in order\n); });测试断言分两层第一编译必须成功result.ok true——证明在types/node类型化下process.argv/process.env/process.stdout.write全部静态降级、没有产生任何栅栏第二编译出的原生二进制必须行为正确——带[alpha, beta]运行argv 计数输出2、逐项输出alpha、beta再从环境变量输出hi from env最后验证无换行的字节写出written without newline与后续log的- flushed in order顺序衔接。README 中描述的「the binary runs」正是由这组双断言钉死的。同类受支持表面的测试还有URL 的port/hashgetter 静态降级L91 起、被捕获的NodeJS.WritableStream值经procStream标量写出、refined spawn 返回值暴露可写子进程 stdin、回调式execFile使用类型化的 error-first 重载、path/os在 types/node 形状下静态降级、fetch的AbortSignal与可读 body 静态降级、全局与node:util编解码器实例共享存储的原生表示、导入的console方法共享原生输出格式化等见 tests/harness/project-config.test.ts 的 node-types 系列。五、声明但未降级的表面SC2020 家族栅栏5.1 设计原则宁要明确的编译失败不要损坏的二进制README 对 fenced.ts 的定位非常明确表面是types/node声明的但 scriptc 不降级。对这类表面types/node负责让所有使用处通过类型检查而 scriptc 必须让编译以 SC2020 家族栅栏失败、并在诊断中点名types/node——绝不落入裸的Cannot find name类型错误也绝不 typecheck 出一个运行时会崩溃的损坏二进制。这一原则的源码依据在 packages/compiler/src/diagnostics/diagnostic.ts 的栅栏代码注册表SC2020: { name: standard-library or types/node surface with no lowering, status: unsupported },SC2020 属于FENCE_CODES中的 construct-fence 代码由工厂函数铸出永不作为UNSUPPORTED的键状态为unsupported——即两个 tier静态与--dynamic都没有降级实现。诊断消息的通用形态是「featureis typed by types/node but has no scriptc lowering yet」并附带 hint 说明支持面或替代途径例如use --dynamic for the wider Web API。5.2 逐项走读 fenced.ts 的栅栏行为fenced.ts是这份「声明但未降级表面」的完整清单值得逐段分析process / Bufferconsole.log(process.memoryUsage()); // V8-heap 报告不降级 console.log(Buffer.poolSize);注释说明uptime/cpuUsage/resourceUsage现在已能降级但 V8-heap 内存报告memoryUsage()不在其中Buffer.poolSize同样栅栏。快照 node-types-fenced.txt 给出了真实诊断输出fenced.ts:5:13 - error SC2020: process.memoryUsage is typed by types/node but has no scriptc lowering yet hint: the type checker sees everything types/node declares, but only the supported surface compilessetInterval 的 Timeout 返回值const timer setInterval(() { console.log(tick); }, 1000); timer.unref(); timer.refresh(); timer.close();setInterval本身会降级且其Timeout返回值在types/node下映射为数值句柄numeric handle持有该返回值并调用unref()/ref()/hasRef()/refresh()都能编译但超出该子面的Timeout表面如close、[Symbol.toPrimitive]保持栅栏——快照中正是Timeout.close is typed by types/node but has no scriptc lowering yethint 提示unref(), ref(), hasRef(), and refresh() are the supported Timeout methodsnode-types-fenced.txt。这也印证了 lower-builtins.ts 中注释提到的「fallback 的Timeout或 types/node 的NodeJS.Timeout」由 provenance 参与识别的设计。web 平台全局undiciconst fetchInit: RequestInit { method: POST, headers: {...}, body: {} }; fetch(https://example.invalid/, fetchInit); async function inspectResponse(url: string): Promisevoid { const response await fetch(url); console.log(response.type); response.clone(); } ReadableStream.from(new Set([1, 2]));fetch、AbortController、类型化的RequestInit均降级但更宽的Response成员type、clone保持各自的 profile 栅栏——快照中Response.type in a static build的 hint 明确给出原生静态Response支持面status/ok/statusText/url/redirected/headers/body/bodyUsed加上json()/text()/bytes()并提示use --dynamic for the wider Web APInode-types-fenced.txt。后续body.tee()、body[tee]括号访问等可读流成员同样栅栏。受支持内建模块的溢出成员module-qualified fenceimport { watchFile } from fs; import { cpus } from node:os; import { win32 } from path; watchFile(x, () {}); console.log(cpus().length); console.log(win32.sep);这些模块fs/os/path整体受支持但超出降级表的成员watchFile、cpus、win32在types/node下通过类型检查却以**模块限定名module-qualified**栅栏——调用与值读取一律如此。URL getter 子面const u new URL(https://example.com/x?a1); console.log(u.toJSON()); u.searchParams.get(a);URL 的port/hash/password等 getter 在types/node下降级有独立测试 L91 起 验证但未实现成员仍按成员名栅栏并附受支持清单searchParams及其方法表面在types/node的声明下降级像 URL 本身一样做 provenance 映射。zlib 编解码器import { brotliCompressSync, deflateSync } from zlib; deflateSync(data, { level: 9, strategy: 1 }); brotliCompressSync(Buffer.from(data));一次性 zlib/raw/gzip 编解码器接受字面量压缩等级level: 9, strategy: 1其他选项保持栅栏而 Brotli 保持成员限定栅栏、并在 hint 中指名已降级的家族。http2 兼容切片divergence 56import * as http2 from node:http2; http2.createSecureServer({ allowHTTP1: true, cert: pem, key: pem, SNICallback: undefined }); http2.createSecureServer({ ...(1 ? { SNICallback: undefined } : {}) }); http2.createSecureServer({ ..., streamResetBurst: 1 0 }); http2.connect(https://localhost);SNICallback选项按名称栅栏并带 serve-one-pair 提示其 conditional-spread portless 拼写在 spread 处栅栏因为只有内联对象字面量才会展平计算式 spread 不会非字面量的 h2 session-tuning 值如1 0计算的streamResetBurst栅栏——字面量会被接受并忽略因为没有 h2 session 可调connect以 client gap 命名并在 hint 中给出 fallback。crypto 超出降级切片的部分import { createCipheriv, generateKeyPair, pbkdf2Sync, setFips } from node:crypto; generateKeyPair(rsa, { modulusLength: 2048 }, () {}); createCipheriv(aes-128-cbc, Buffer.alloc(16), Buffer.alloc(16)); pbkdf2Sync(pw, salt, 100000, 64, sha512); setFips(false);在已降级的 crypto 切片随机数、哈希链、内省 statics之外非对称密钥操作点名缺失的公钥栈public-key stack、对称密码点名缺失的密码栈cipher stack、KDF 点名其家族、setFips点名 FIPS 真值——顺带一提getFips()是能降级到0的。fetch的integrity选项同样栅栏。5.3 快照测试把栅栏钉成固定输出project-config.test.ts 的 L235-L247 对fenced.ts编译失败路径做了快照断言编译必须失败result.ok false将诊断渲染后与snapshots/node-types-fenced.txt 逐字节比对。这保证了任何对types/node类型表面或降级表的改动若导致栅栏代码、消息文案或 hint 变化都会被测试立即捕获——结合第二节的版本锁定整条链路的可复现性由此闭环。六、跨模块类型采纳source-import/ 与 RequestInfo 全局6.1 场景与样本fixture 中的source-import/目录验证一个更微妙的组合场景被导入的 TypeScript 源码使用了 TypeScript 默认 DOM lib 提供的RequestInfo全局而 scriptc 同时采纳项目的types/node声明。source-import/dependency.ts 定义了一个引用该全局的类型export type RequestHandler (input: URL | RequestInfo) void; export const message source fetch types resolve;source-import/main.ts 则是标准的跨文件导入import { message } from ./dependency.ts; console.log(message);目录内另有package.json声明{type:module}将导入语义固定为 ESM。这里的关键点在于RequestInfo并非来自types/node而是来自 TypeScript 自身的默认 DOM lib在采纳types/node的项目中这两套类型来源会同时存在于编译程序中。fixture 要证明的是这样的类型解析对 scriptc 的降级流程是良性的——依赖模块可以正常类型化、正常编译跨文件类型引用不会因为「types/node 接管」而被误伤。6.2 harness 验证对应的测试为 project-config.test.ts 的node-types: imported TypeScript sources can use the RequestInfo global。它把source-import/main.ts作为入口编译验证导入链完整通过。这个用例回答了一个真实项目里最常见的问题当我把一个用了 DOM/Web 全局RequestInfo、fetch、Response等的模块 import 进一个安装types/node的项目时会不会因为类型来源混杂而编译失败答案是否定的——scriptc 对「types/node 声明的表面」与「TypeScript 默认 lib 提供的表面」分别处理各自按自己的降级规则执行。七、没有 types/node 的项目行为完全不变README 的最后一段给出了这条采纳路径的边界条件Projects WITHOUTtypes/node(every other fixture and the whole corpus) keep the shipped fallback declarations and behave exactly as before.结合 dts-paths.ts 的实现这一句包含两层含义注入层面无types/node时fallbackDtsPath()指向的scriptc-node-fallback.d.tsconsole、process、node:fs照常注入程序有types/node时该文件让位避免声明冲突行为层面同一份用户源码在两个世界中只要落在降级表内就降级到同一组 libCall——因此「with types/node」不会改变任何已支持表面的编译结果只会新增a) 更精确的 Node 类型原本 fallback 声明不覆盖或覆盖较粗的类型b) 对「声明但未降级」表面从「可能报裸类型错误」升级为「精确命名的 SC2020 栅栏」。从源码结构看这正是设计上的刻意对称fixture 只在「类型来源」上做切换不在「降级行为」上分叉。对维护者而言这意味着新增一个 node-types 之外的 fixture 或语料库用例时无需担心types/node的在场与否会悄悄改变既有编译语义。八、如何在真实项目中复用这套机制把上述机制落到自己的 Node/TypeScript 项目上实践要点如下在devDependencies中固定types/node版本如types/node: 24.13.3使类型表面可复现若项目还需要 web 平台全局undici-types会随types/node一并进入无需单独声明。理解「类型检查通过 ≠ 可以编译」types/node会让所有声明处的代码通过 tsc 的类型检查但 scriptc 只降级受支持的子面。遇到SC2020诊断时先读 hint——它要么给出该成员的实际受支持子面如 Timeout 的unref()/ref()/hasRef()/refresh()要么给出替代途径如--dynamic下的更宽 Web API。利用栅栏而非规避类型对「声明但未降级」的表面正确做法是让编译在 CI 中明确失败并暴露诊断像 fenced.ts 的快照测试那样钉住行为而不是用any绕过类型系统——绕过只会把「编译期可知的问题」推迟成运行时的损坏二进制。按需迁移到受支持子面如果项目依赖process.memoryUsage()这类未降级成员可以围绕其 hint 中列出的受支持成员如uptime()/cpuUsage()/resourceUsage()重构代码使程序进入可静态编译的集合。在仓库内做同样的版本锁定与快照测试仿照本 fixture 将node_modules作为已提交测试数据配合toMatchFileSnapshot式的诊断快照可以让「types/node 升级导致类型表面漂移」这一类回归在第一时间被发现。结语node-types fixture 用一份极小但信息密度极高的测试目录完整演示了 scriptc 对真实 Node/TypeScript 项目的接入策略版本锁定的types/node与undici-types提供可信类型表面dts-paths.ts 中的fallbackDtsPath()/isNodeTypesPath()完成声明切换与 provenance 识别diagnostic.ts 中的 SC2020 家族栅栏保证「声明但未降级」的表面以精确诊断失败而非损坏二进制收场而 project-config.test.ts 与 node-types-fenced.txt 把这一切钉成可复现的断言。理解这条路径是让真实世界项目顺利进入 scriptc 静态编译世界的第一步。赞分享编译器语言运行时开发工具CLI【免费下载链接】scriptcTypeScript-to-Native Compiler项目地址https://gitcode.com/GitHub_Trending/sc/scriptc点击查看免费下载相关推荐Nerd让JavaScript编译为原生二进制Nerd让JavaScript编译为原生二进制 项目介绍 Nerd 是一个 JavaScript 原生编译器旨在使 JavaScript 变得更加通用。它可node-fetch TypeScript类型定义完全指南types/node-fetch使用详解node fetch TypeScript类型定义完全指南types/node fetch使用详解 概述 TypeScript类型定义Type Defin后端scriptc 变更全览从 TypeScript 到原生可执行文件的编译器演进路线scriptc 变更全览从 TypeScript 到原生可执行文件的编译器演进路线 scriptc 是一个把 TypeScript 和 JavaScript编译器语言运行时开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考