TypeSpec CLI 完全指南：tsp 命令详解与 TYPESPEC_NPM_REGISTRY 环境变量实战

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 TypeSpec's output to make compiler error s easier to read. [boolean] [default: true] --version Show version number [boolean]

从源码实现看，上述命令与选项由 cli.ts 中的 yargs 配置驱动（runTypeSpecCli函数）。该文件还揭示了帮助输出之外的两个细节：

• --trace <area>选项：帮助输出中未直接列出，用于指定需要输出 trace 日志的领域，例如--trace='import-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在源码中通过resolvePath(cwd, pathArg)解析为绝对路径；若以{开头则按配置占位符原样透传，见 args.ts。

emitter 与产物控制

--options的解析逻辑位于 args.ts：先用=拆分键值，再用.拆分层级，最终组装为{ emitterName: { key: value } }结构；若键不含.则归入miscOptions传给 emitter。该选项与--emit的联动可在编译时临时覆盖 emitter 行为，无需改动tspconfig.yaml。

诊断与观察

典型用法示例：

# 编译当前目录的 main.tsp 并将产物输出到 ./dist tsp compile . --output-dir ./dist # 指定 emitter 并临时覆盖其选项 tsp compile . --emit @typespec/openapi3 --options @typespec/openapi3.file-type=json # 监听模式开发 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

支持的选项：

⚠️ 安全警告（官方文档原文强调）：当使用外部模板 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

支持的选项：

formatAction在 format.ts 中实现：默认模式调用formatFiles直接格式化并统计formatted/unchanged/ignored/error四类结果；--check模式调用checkFilesFormat，只要存在需要格式化的文件（needsFormat）或错误即以退出码1失败，这正是 CI 流水线中“格式不合规即构建失败”的标准用法。

tsp install：安装 TypeSpec 依赖

tsp install用于安装 TypeSpec 项目依赖。其实现位于 install.ts，核心流程是：

1. 读取项目package.json，解析其中声明的包管理器（packageManager字段或devEngines.packageManager）；若未声明，默认回退到npm latest并给出警告（no-package-manager-spec），见 install.ts；
2. 通过 npm registry 获取该包管理器的 manifest，下载并解压其 tarball，按需校验哈希（spec.hash）后缓存到用户缓存目录；
3. 以fork方式在项目目录下运行包管理器的install命令完成依赖安装。

支持的选项：

若项目中没有package.json，会直接报错 "No package.json found, cannot install dependencies."（install.ts）。

tsp info：查看编译器与配置信息

tsp info [emitter]打印当前 TypeSpec 编译器的信息，见 info.ts：

• tsp 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.ts）：

• tsp code通过调用本机的code可执行文件执行--install-extension microsoft.typespec-vscode；--insiders选项会改用code-insiders；
• 若系统 PATH 中找不到code，会返回vscode-in-path诊断，提示将 VS Code CLI 加入 PATH（macOS 与其它平台的提示文案不同）；
• 注意：tsp code install/uninstall已被标记为deprecated（reportDeprecatedCommand），官方建议直接从 VS Code 扩展市场安装或卸载，见 vscode.ts；
• tsp 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_REGISTRY=https://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(/\/$/, ""); }

两个值得注意的实现细节：

1. 尾部斜杠会被剔除：getNpmRegistry()通过.replace(/\/$/, "")去掉 registry URL 末尾的/，因此https://my-registry.com/与https://my-registry.com写法等价；
2. registry 请求格式：fetchPackageManifest会向${getNpmRegistry()}/${packageName}发起请求，并携带Accept: application/vnd.npm.install-v1+json头（针对 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 的.npmrc）；
• TypeSpec不会读取包管理器的认证配置，因此 registry 返回的包元数据请求与 tarball URL 必须能被 TypeSpec 进程直接访问。

原因从源码可见：TypeSpec 进程只负责两件事——通过getNpmRegistry()指向的 registry 发起元数据（manifest）请求，以及随后下载 tarball（downloadAndExtractPackage，见 install.ts）。tarball URL 来自 registry 返回的dist.tarball字段，如果私有 registry 返回的 tarball 地址指向需要认证的内网主机，而 TypeSpec 进程本身没有访问凭证，安装仍会失败。因此若使用需认证的私有 registry，务必同时保证：① 包管理器自身配置好认证（用于tsp init之后的npm install等环节）；② TypeSpec 进程能匿名或通过其可用的网络通道访问 registry 的元数据接口与 tarball。

总结与速查

掌握以上命令与TYPESPEC_NPM_REGISTRY的边界后，你既可以在日常开发中高效驱动 TypeSpec 编译、格式化与项目初始化，也能在企业网络环境中正确接入私有 npm 镜像，避免因 registry 配置错位导致的下载失败。

【免费下载链接】typespec项目地址: https://gitcode.com/GitHub_Trending/ty/typespec