如何使 4.X Typescript 项目与旧版本的 Typescript（如 3.X）兼容？

如何使基于 TS 4.X 构建的软件包与 3.X 兼容？例如，如果我有较新的版本，则使用新功能，否则使用any or unknown或旧版本支持的任何内容。

有没有可能使用指令 https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html为了这个目的？

Preface

^{This answer assumes the question is about taking source code (.ts) of a project written using TypeScript 4.x constructs and making type declaration files (.d.ts) emitted from them compatible with a TypeScript 3.x compiler for the benefit of the users of the package- as opposed to writing source code that uses 4.x constructs and somehow making it compatible with a 3.x compiler (the way the question is phrased is ambiguous with respect to this). I make this assumption because:}

• ^{If you decide you want to use language features in your source code that aren't supported by older compiler versions, you are (whether you realize it or not) making a decision to drop support for building the project using those older compiler version. If you have a strong reason to want to support building the project using those older compilers, then I'm pretty sure you just have to not use those newer language features (or somehow convince the maintainers of the compiler to backport those changes to older compiler versions, which I think is pretty rare).}

• ^{I'm not personally aware of any reasons not to upgrade your compiler version unless you have very strict security policies and require your dependencies and build tooling to be audited. I'd wager that that's pretty rare in the JavaScript development scene where the landscape is known for changing rapidly.}

downlevel-dts

注意：TypeScript 具有“降级”其发出的 JavaScript 的功能，可将 ECMA Script 标准较新版本的语言结构转换为可在旧版本中使用的结构。 （看the compileOptions.targettsconfig 字段 https://www.typescriptlang.org/tsconfig#target).

据我所知，TypeScript 本身没有这样的功能来降低级别typings它发出的文件（包括撰写本文时的三斜杠指令），但 Nathan Sanders（Definitely Typed 的维护者）维护一个开源项目，downlevel-dts, 降级 .d.ts 文件 https://github.com/sandersn/downlevel-dts它可以将打字一直降低到 typescript v3.4 语法。

package.json.typesVersions 和 semver-ts.org

semver-ts.org 的“‘降级’类型”部分 https://www.semver-ts.org/#downleveling-types解释了如何为引入了新的非向后兼容语言构造的每个打字稿版本编写降级类型的脚本，以及如何告诉包用户的编译器要使用哪个版本的类型以及在哪里可以找到它们：

当新版本的 TypeScript 包含向后不兼容的更改时发出的类型定义，就像他们在3.7 https://github.com/microsoft/TypeScript/pull/33470，直接改变类型的策略可能行不通。但是，仍然可以使用以下组合来提供向后兼容的类型下层dts https://github.com/sandersn/downlevel-dts and 类型版本 https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-1.html#version-selection-with-typesversions。 （在某些情况下，这可能还需要对类型进行一些手动调整，但这对于大多数包来说应该很少见。）

• The downlevel-dts工具允许您采取.d.ts对于早期版本的 TypeScript 无效的文件（例如，对类字段发出的更改中提到的重大变化 https://www.semver-ts.org/#breaking-changes），并发出与该版本兼容的版本。它支持针对 3.4 之后的所有 TypeScript 版本。

• TypeScript 支持使用typesVersions键入一个package.json文件来指定一组特定的类型定义（可能包含一个或多个.d.ts文件）对应于特定的 TypeScript 版本。

推荐的流程如下：

为了避免从场外材料中复制太多（抄袭），我将用自己的话总结这些步骤（请阅读带有示例的完整步骤的源代码）：

1. Install downlevel-dts作为开发依赖项（以及其他一些辅助工具）。
2. Call downlevel-dts将类型降级为您想要支持的旧类型声明版本（这可以编写脚本）。
3. 更新您的 package.json 以在生成最新类型声明版本的类型后注册调用您的脚本。
4. 使用以下命令在 package.json 文件中注册生成的旧版本类型声明文件typesVersions field.
5. 确保生成的文件包含在包的文件中（更新files字段，或您正在使用的任何类似字段）。

的局限性downlevel-dts

请注意，存在一些限制。以下是引自downlevel-dts的自述文件：

请注意，并非所有功能都可以降低级别。例如，TypeScript 4.0 允许在元组中的任何位置分布多个元组类型变量。这在以前的版本中是不允许的，但没有明显的下层发射，因此下层 dts 不会尝试执行任何操作。请务必使用适当版本的 TypeScript 测试 downlevel-dts 的输出。

其他提议的解决方案的问题方面：

• “使用较旧的打字稿版本来发出您的打字”

  • 这假设问题的提出者正在使用 TS 编译器从 .ts 文件发出类型，并且如果他们手动维护它们则不起作用，这对于首先用 JS 编写的非常大的项目来说通常是这种情况没有带宽迁移到 TS。
  • 这可能需要你制作你的 .ts源代码 to not use在比编译器更新的版本中引入的 TypeScript 语言构造，您必须使用它来发出要发出的 TypeScript 语言版本中的类型。这并不理想，因为使用较新的语言结构编写代码可能会更干净，或者不可能仅使用较旧的结构来执行某些操作。

• “维护两种 TypeScript 语言版本的类型”

  • 这似乎做出了相反的假设：该项目为手动编写的 JS 代码维护手动类型文件，而不是转换为 .js 并从 .ts 文件发出 .d.ts。
  • 这是一个big维护负担（手动维护.d.ts文件已经是很大的维护负担了！）。对于小型项目来说这可能是可以接受的，但对于具有大型或复杂 API 表面的库来说则不然。