meteor-typescript

Meteor 应用中的 TypeScript

让编辑器和检查器解析预期的 Meteor 声明，并实际检查应用源代码。除非任务要求更改，否则保留当前可用的提供方选择。升级运行时或打包器并不意味着要迁移声明。

对于运行时迁移或打包器配置请求，在提出迁移步骤或构建配置之前，先加载负责该事项的技能。此技能中的声明指南不提供相应流程；如果无法获取负责该事项的技能，请勿用通用 TypeScript/Rspack 方案替代。

确定所在层

层	证据和操作
编译	Atmosphere typescript 包或 Rspack/SWC 会剥离类型。语法转换、加载器和打包请使用负责构建的组件。
声明提供方	检查 .meteor/packages、.meteor/versions、npm/工作区清单和锁文件，确认是否直接使用 zodern:types、@types/meteor，以及是否原生选择启用。
解析	检查当前使用的 tsconfig.json/jsconfig.json、extends、files、include、exclude、paths 和 types。确认编辑器使用的是预期的项目/编译器。
检查	检查已安装的 npm typescript 和脚本；它们与 Atmosphere 编译器相互独立。保留已配置的检查器，例如 TsCheckerRspackPlugin。

不要因为 meteor run 或 meteor build 成功，就推断应用经过了检查。反之，也不要仅仅因为 SWC 本身只会转译，就声称明确配置的检查器从未运行。

选择提供方

原生声明始于 3.6-beta.1；此工作流已通过 3.6-beta.3 验证，并对照 3.6-rc.0 源码检查。Beta.3 增加了下方链接中的声明修正；RC 仍要求显式生成并选择提供方。

目标和意图	决策
低于 3.6-beta.1 的 Meteor 3	无法使用原生 meteor types。保留可用的旧版提供方；如果缺少声明，请参阅提供方参考中的早期版本分支。
支持原生类型的 3.6 新应用或现有应用，且旧版类型可用	除非要求采用原生类型，否则予以保留。Beta.1 TypeScript 模板仍会安装直接依赖 zodern:types 和 @types/meteor；原生回退路径并非选择启用。
在 3.6-beta.1 至 beta.3 或 3.6-rc.0 中显式采用原生类型	必须配置根目录配置文件。记录当前提供方/配置，移除直接依赖 zodern:types，成功生成后，再合并原生解析配置并移除重叠的环境声明类型。
希望获得 IntelliSense 的纯 JavaScript 3.6 Beta 应用	使用 jsconfig.json，并采用相同的提供方选择；无需转换 TypeScript 源码，也无需切换打包器。

阅读声明提供方，了解有序切换步骤、原生适配器与入口文件的区别、继承配置、TypeScript 7 兼容性、早期提供方和回滚。JavaScript 应用请阅读 JavaScript IntelliSense。

验证项目是否生效

1. 确认生成确实已运行。直接使用 zodern:types 会导致 meteor types 跳过并以零退出；在 beta.1 到 beta.3 或 RC 版本中，普通 Meteor 命令不会选择或重新生成原生声明。
2. 使用应用本地的编译器。使用原生声明时，在包脚本中运行 meteor types && tsc --noEmit；如果应用有多个项目，请明确选择目标配置。
3. 检查 tsc --listFiles --noEmit 是否包含应用源代码。在 files 下追加一个 barrel 文件可能会停用隐式包含；请保留现有的源代码模式和排除项。故意临时加入错误类型应导致检查失败；移除探针后重新运行。仅有 JavaScript IntelliSense 并不会启用 checkJs；如有需要，请单独启用 JS 检查。
4. 更改配置后，重启编辑器的 TypeScript 服务器。如果 CLI 与编辑器的结果不一致，请先比较所选配置和编译器，再清除 Meteor 状态或重新安装提供程序。
5. 保持生成的 .meteor/types/ 不受版本控制且不做编辑。请修复暴露出来的应用错误，而不要用 any 或新的 skipLibCheck 绕过来掩盖问题。

诊断边界问题

症状	首先检查
原生命令提示无需执行任何操作	根目录下的 tsconfig.json 或 jsconfig.json。对于新的纯原生配置，请先使用根配置生成，再添加指向不存在输出的条目。
生成失败	阅读错误信息；可能需要修复本地包。停止切换提供程序，保留配置和旧输出，并恢复之前的提供程序以便回滚。
普通导入正常，但带作用域或子路径的导入失败	在 files 中显式添加原生 barrel 文件，并将通配符映射到各个包的适配器，而不是映射到 barrel 文件。
标识符重复	检查是否有多个提供程序、继承的 types: ["meteor"]，以及符号链接之前的应用环境声明。
Meteor 的包存储中的 peer 类型失败	考虑针对该特定边界使用 preserveSymlinks；它无法移除重复的提供程序。
某个社区包仍然没有类型	检查已安装的包是否发布了声明。任何生成器都无法保证覆盖每个 Atmosphere 包。
生成的相对导入或订阅句柄类型与运行时不一致	查看提供程序指南中的 beta.3 声明修正，然后重新生成并进行类型检查。不要编辑生成的文件，并确保结构化句柄可用。

如果实际任务是发布包声明，请使用官方的 Atmosphere 包类型文档。 不要将编辑生成的应用适配器作为编写包的解决方案。