TypeSpec CLI 完全指南tsp 命令详解与 TYPESPEC_NPM_REGISTRY 环境变量实战【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec导读TypeSpec 编译器tsp是 TypeSpec 语言日常开发的核心工具涵盖编译、格式化、项目初始化、依赖安装与扩展管理等全部工作流。本文以官方 CLI 使用文档为骨架结合编译器源码packages/compiler/src/core/cli/深入讲解每一个子命令、全局选项以及TYPESPEC_NPM_REGISTRY环境变量的底层实现帮助你准确掌握tsp命令行工具的真实行为并在企业内网等需要私有 npm 镜像的场景中正确配置 TypeSpec。tsp 命令总览TypeSpec 编译器的命令行入口是tsp。在终端中直接输入以下命令即可看到全部支持的命令与选项官方文档亦以该命令输出作为权威参考tsp --help TypeSpec compiler v0.36.1 tsp command Commands: tsp compile path Compile TypeSpec source. tsp code Manage VS Code Extension. tsp vs Manage Visual Studio Extension. tsp format include... Format given list of TypeSpec files. tsp init [templatesUrl] Create a new TypeSpec project. tsp install Install TypeSpec dependencies tsp info Show information about the current TypeSpec compiler. Options: --help Show help [boolean] --debug Output debug log messages. [boolean] [default: false] --pretty Enable color and formatting in TypeSpecs output to make compiler error s easier to read. [boolean] [default: true] --version Show version number [boolean]从源码实现看上述命令与选项由 cli.ts 中的 yargs 配置驱动runTypeSpecCli函数。该文件还揭示了帮助输出之外的两个细节--trace area选项帮助输出中未直接列出用于指定需要输出 trace 日志的领域例如--traceimport-resolution.*而--debug等价于--trace*开启全部追踪见 cli.ts版本号显示差异--version在标准安装下显示编译器版本号在 standalone 自包含环境下则会追加standalone后缀${typespecVersion} standalone见 cli.ts。此外CLI 会拦截tsp compile --emit emitter --help这一特殊组合当compile命令携带--help且同时指定了--emit时yargs 的通用帮助不会生效而是直接打印该 emitter 支持的全部选项printEmitterOptionsAction详见 cli.ts。这是探索某个 emitter 配置项最快捷的方式。tsp compile编译 TypeSpec 源码tsp compile path是使用频率最高的命令path既可以是main.tsp文件的路径也可以是包含main.tsp的目录由resolveTypeSpecEntrypoint解析见 compile.ts。该命令支持丰富的选项全部定义在 args.ts 与 cli.ts 中下面按用途分组说明输入与输出控制选项类型说明--output-dir pathstring生成产物的输出目录不存在时会自动创建也支持{cwd}等占位符形式的配置值--config pathstring指定 TypeSpec 配置文件YAML路径或包含tspconfig.yaml的文件夹路径--nostdlibboolean不加载 TypeSpec 标准库默认false用于自定义标准库的极端场景--import modulearray附加导入可多次使用以追加多个模块--arg keyvaluearray以键值对形式传入配置中使用的参数别名--args其中--output-dir在源码中通过resolvePath(cwd, pathArg)解析为绝对路径若以{开头则按配置占位符原样透传见 args.ts。emitter 与产物控制选项类型说明--emit emitterarray指定要运行的 emitter 名称可多次使用--options emitter.keyvaluearray以emitterName.keyvalue格式设置 emitter 选项可多次使用别名--option--no-emitboolean不运行任何 emitter只做编译与类型检查--dry-runboolean运行 emitter 但只支持该特性的 emitter 不写出任何输出--list-filesboolean仅列出将生成的产物文件路径不实际生成--warn-as-errorboolean将警告视为错误存在警告时返回非零退出码--options的解析逻辑位于 args.ts先用拆分键值再用.拆分层级最终组装为{ emitterName: { key: value } }结构若键不含.则归入miscOptions传给 emitter。该选项与--emit的联动可在编译时临时覆盖 emitter 行为无需改动tspconfig.yaml。诊断与观察选项类型说明--watchboolean监听项目文件变化并自动重编译默认false由 watch.ts 实现--statsboolean打印编译统计信息任务耗时、创建的类型数量等见 args.ts--ignore-deprecatedboolean抑制所有deprecated诊断默认false--trace area/--debugarray / boolean输出指定领域或全部*的 trace 日志典型用法示例# 编译当前目录的 main.tsp 并将产物输出到 ./dist tsp compile . --output-dir ./dist # 指定 emitter 并临时覆盖其选项 tsp compile . --emit typespec/openapi3 --options typespec/openapi3.file-typejson # 监听模式开发 tsp compile . --watch # 仅做类型检查不产出任何文件 tsp compile . --no-emit当编译出错时compileAction会打印诊断并以退出码1结束进程program.hasError()时process.exit(1)见 compile.ts。tsp init创建新的 TypeSpec 项目tsp init [templatesUrl]用于交互式创建 TypeSpec 项目可选地传入模板 URL 以使用外部初始化模板底层调用initTypeSpecProject见 init.ts。# 交互式选择内置模板 tsp init # 使用外部模板 URL 初始化注意安全风险见下方警告 tsp init https://example.com/my-templates支持的选项选项说明--template name指定要使用的模板名称--no-prompt/-y自动接受所有有默认值的提示默认false--project-name name指定项目名称--template-emitters emitters指定要包含进项目的 emitters模板未声明的 emitter 会被忽略默认 emitters 始终包含--output-dir path产物输出路径该目录必须已存在与compile的--output-dir自动创建不同--arg keyvalue/--args传入初始化模板使用的键值参数⚠️ 安全警告官方文档原文强调当使用外部模板 URL 执行tsp init时下载或使用不受信任的模板可能包含恶意包从而危害你的系统和数据。请务必谨慎行事并核实模板来源。该警告同样体现在 CLI 源码的templatesUrl参数描述中cli.ts。--output-dir在实现中经resolvePath(process.cwd(), outputDir)解析为绝对路径未指定时默认使用当前工作目录见 init.ts。tsp format格式化 TypeSpec 文件tsp format include...接收一个或多个通配符模式glob来指定要格式化的文件# 格式化当前目录及子目录下所有 .tsp 文件 tsp format **/*.tsp # 排除 node_modules并校验格式是否符合规范 tsp format **/*.tsp --exclude node_modules/** --check支持的选项选项别名说明--exclude pattern-x要排除的模式可多次使用--check-c只校验文件是否已格式化CI 中常用不实际改写文件formatAction在 format.ts 中实现默认模式调用formatFiles直接格式化并统计formatted/unchanged/ignored/error四类结果--check模式调用checkFilesFormat只要存在需要格式化的文件needsFormat或错误即以退出码1失败这正是 CI 流水线中“格式不合规即构建失败”的标准用法。tsp install安装 TypeSpec 依赖tsp install用于安装 TypeSpec 项目依赖。其实现位于 install.ts核心流程是读取项目package.json解析其中声明的包管理器packageManager字段或devEngines.packageManager若未声明默认回退到npm latest并给出警告no-package-manager-spec见 install.ts通过 npm registry 获取该包管理器的 manifest下载并解压其 tarball按需校验哈希spec.hash后缓存到用户缓存目录以fork方式在项目目录下运行包管理器的install命令完成依赖安装。支持的选项选项说明--save-package-manager将解析到的包管理器版本与哈希写回package.json的packageManager字段若项目中没有package.json会直接报错 No package.json found, cannot install dependencies.install.ts。tsp info查看编译器与配置信息tsp info [emitter]打印当前 TypeSpec 编译器的信息见 info.tstsp info无参数输出编译器模块路径、解析到的用户配置文件路径User Config: path或No config file found以及合并后的完整配置内容YAML 格式tsp info emitter输出指定 emitter 包支持的选项等价于tsp compile --emit emitter --help的效果tsp info features输出当前编译器的 feature 开关状态列表enabled/disabled 与说明。tsp code 与 tsp vs管理编辑器扩展tsp code管理 VS Code 扩展tsp vs管理 Visual Studio 扩展二者均提供install与uninstall子命令tsp code install # 安装 TypeSpec VS Code 扩展 tsp code uninstall # 卸载 TypeSpec VS Code 扩展 tsp vs install # 安装 TypeSpec Visual Studio 扩展 tsp vs uninstall # 卸载 TypeSpec Visual Studio 扩展实现细节vscode.tstsp code通过调用本机的code可执行文件执行--install-extension microsoft.typespec-vscode--insiders选项会改用code-insiders若系统 PATH 中找不到code会返回vscode-in-path诊断提示将 VS Code CLI 加入 PATHmacOS 与其它平台的提示文案不同注意tsp code install/uninstall已被标记为deprecatedreportDeprecatedCommand官方建议直接从 VS Code 扩展市场安装或卸载见 vscode.tstsp vs的安装逻辑在 vs.ts 中帮助信息同样建议改用 Visual Studio Marketplace。TYPESPEC_NPM_REGISTRY为企业环境配置 npm 镜像作用与用法TYPESPEC_NPM_REGISTRY环境变量用于设置 TypeSpec 在以下两个场景中访问的 npm 兼容 registry 地址tsp init解析模板依赖的包版本时tsp install下载配置的包管理器npm / pnpm / yarn 等时。在企业内网、离线环境或需要统一镜像源的环境中可这样使用TYPESPEC_NPM_REGISTRYhttps://my-corp-registry.example.com tsp init默认值若未设置该变量TypeSpec 默认使用https://registry.npmjs.org。底层实现该环境变量在 npm-registry.ts 中读取const defaultRegistry https://registry.npmjs.org; export function getNpmRegistry(): string { return (process.env[TYPESPEC_NPM_REGISTRY] ?? defaultRegistry).replace(/\/$/, ); }两个值得注意的实现细节尾部斜杠会被剔除getNpmRegistry()通过.replace(/\/$/, )去掉 registry URL 末尾的/因此https://my-registry.com/与https://my-registry.com写法等价registry 请求格式fetchPackageManifest会向${getNpmRegistry()}/${packageName}发起请求并携带Accept: application/vnd.npm.install-v1json头针对 npm registry API 的压缩 manifest 格式随后解析dist-tags与versions选择匹配版本支持 dist-tag 与 semver 范围两种解析方式见 npm-registry.ts。scoped 包名如scope/pkg中的/会被编码为%2F。重要边界不接管包管理器的认证与配置官方文档特别强调TYPESPEC_NPM_REGISTRY并不配置tsp init或tsp install所调用包管理器的 registry 与认证包管理器自身的 registry 和认证设置需要在其自己的配置中单独配置如 npm 的.npmrcTypeSpec不会读取包管理器的认证配置因此 registry 返回的包元数据请求与 tarball URL 必须能被 TypeSpec 进程直接访问。原因从源码可见TypeSpec 进程只负责两件事——通过getNpmRegistry()指向的 registry 发起元数据manifest请求以及随后下载 tarballdownloadAndExtractPackage见 install.ts。tarball URL 来自 registry 返回的dist.tarball字段如果私有 registry 返回的 tarball 地址指向需要认证的内网主机而 TypeSpec 进程本身没有访问凭证安装仍会失败。因此若使用需认证的私有 registry务必同时保证① 包管理器自身配置好认证用于tsp init之后的npm install等环节② TypeSpec 进程能匿名或通过其可用的网络通道访问 registry 的元数据接口与 tarball。总结与速查场景推荐命令编译并生成产物tsp compile . --output-dir ./dist只做类型检查tsp compile . --no-emit监听重编译tsp compile . --watch查看 emitter 可用选项tsp info emitter或tsp compile . --emit emitter --help格式化/校验格式tsp format **/*.tsp/tsp format **/*.tsp --check创建新项目tsp init [templatesUrl]安装依赖tsp install查看编译器与配置tsp info企业私有镜像前置TYPESPEC_NPM_REGISTRYhttps://...后执行tsp init/tsp install掌握以上命令与TYPESPEC_NPM_REGISTRY的边界后你既可以在日常开发中高效驱动 TypeSpec 编译、格式化与项目初始化也能在企业网络环境中正确接入私有 npm 镜像避免因 registry 配置错位导致的下载失败。【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考