TypeScript 7.1 为 ambient 模块声明引入 import attributes：让类型匹配感知导入属性

• 文档
• 教程

导读：本文解读 TypeScript 7.1 的一项编译器新能力——pattern ambient module 声明（通配符形式的*.css、*.txt等模块声明）现在可以携带 import attributes 类型，使 TypeScript 能够根据import ... with { type: 'css' }这类导入属性区分不同模块的声明。你将理解其匹配规则（可赋值性与"最具体属性类型"优先）、当前限制、声明合并行为，以及项目如何自行定义所需的 ambient 模块。该特性已合并进 TypeScript 7.1.0 Beta 里程碑（对应 PR #63931），由 TypeScript 的原生（Go 实现的）编译器提供支持。

背景：import attributes 是什么

在 TypeScript 5.3 中引入的 Import Attributes（导入属性）为 import 语句附加元信息，告诉运行时如何处理模块（例如 JSON）。它让导入意图更清晰，并契合 Content Security Policy（CSP）对资源加载的安全要求。TypeScript 只负责校验语法合法性，实际解释交由运行时完成。本书英文版在 others.md 的 Import Attributes 小节中给出了两种标准写法：

静态导入：

import config from './config.json' with { type: 'json' };

动态导入：

const config = import('./config.json', { with: { type: 'json' } });

此前 import attributes 只是"让运行时知道如何处理模块"；而 7.1 的新特性把属性信息也纳入了类型系统——当导入携带属性时，TypeScript 可以据此解析到对应的 ambient 模块声明，实现"按属性区分模块类型"。

基础回顾：ambient 模块声明

ambient（环境）声明是描述 JavaScript 代码类型的.d.ts文件，通常用于为现有 JS 库补充类型、或在 JS 文件中标注类型，详见 exploring-the-type-system.md 的 Ambient Declarations 小节。其中declare关键字可以在不导入实现的情况下提供类型定义。常见的类型包通过npm install --save-dev @types/library-name安装，自定义声明则可用 triple-slash 引用引入：

/// <reference path="./library-types.d.ts" />

与此相关的还有 ambient enums——在.d.ts中声明、无对应实现的枚举类型。ambient 机制的整体思路是：类型描述与实现分离，由编译器在编译期使用。

而"pattern ambient module"（通配符 ambient 模块）则用*匹配一类文件路径，例如declare module '*.css'可以为任意 CSS 导入提供类型。7.1 的改动正是落在这一形态上。

核心变化：模式模块声明可声明导入属性类型

TypeScript 7.1 的编译器现在支持在 pattern ambient module 声明上声明 import-attribute 类型。这意味着声明本身可以区分带不同属性的导入，例如区分type: 'css'与type: 'text'。

从语义上理解，一个导入语句可以写成：

import './app.css' with { type: 'css' }; import './README.txt' with { type: 'text' };

过去，无论属性是什么，*.css与*.txt的声明都只能按路径模式匹配；现在声明还可以声明属性类型，从而对"以某种属性导入的同模式模块"给出不同的类型描述（示意性声明形式如下，具体语法以 TypeScript 官方发布为准）：

// 示意：带属性类型的 pattern ambient 声明 declare module '*.css' with { type: 'css' } { const styles: { [key: string]: string }; export default styles; }

匹配规则：可赋值性 + 最具体属性类型

文档明确描述了匹配的两条核心规则：

1. 可赋值性（assignability）匹配：当导入携带属性时，TypeScript 将其与对应的 pattern ambient module 声明做匹配，匹配基础是属性类型间的可赋值性关系。
2. 最具体优先：如果多个声明都匹配同一导入，TypeScript 会选择"属性类型最具体"的那一个。

"最具体"意味着：一个仅声明{ type: 'css' }的声明比一个声明更宽泛类型（如{ type: string }）的声明更优先；多个字符串字面量类型的属性可以形成更细粒度的区分。这为库作者按属性粒度提供不同类型打开了空间——例如同一个模块路径，在type: 'css'属性下与在默认导入下，可以拥有不同的类型形状。

当前限制：字符串字面量类型 + 合并规则

本次实现刻意收窄了能力边界，文档给出了两点明确约束：

• 属性类型目前只能是普通属性，且值必须是字符串字面量类型（string literal types）。换言之，暂不支持计算属性、符号键、对象/数组形态的属性值等复杂形式。
• 合并规则：具有相同 pattern 且属性类型完全相同的声明可以合并（与 TypeScript 的声明合并机制一致）；而属性类型不同的声明保持彼此独立，互不覆盖。

这意味着设计者可以按属性把同一模式拆成多份声明分别描述，只要属性类型互不相同即可共存。

兼容性与工具链现状

该改动是为 TypeScript 7.1.0 Beta 里程碑合并的。需要注意两点：

• 不新增内置声明：标准库不会因此自动包含 CSS 或 text 导入的声明，项目和工具仍需自行定义所需的 ambient 模块（这也是为什么理解上述声明写法依然重要）。
• 原生编译器上下文：TypeScript 7.0 起编译器已切换为新的 Go 实现（见 TypeScript News 索引中关于 7.0 发布的条目），本特性属于这套原生编译器持续推进的一部分。

另外，从版本演进角度看：asserts形式的旧导入关键字在 TypeScript 6.0 已弃用、7.0 成为硬错误（见 getting-started-with-typescript.md 的弃用清单），因此with { ... }是当前及后续版本中唯一推荐写法——7.1 将属性信息接入类型系统，正是建立在这一语法基础之上。

实践建议

1. 工具/库作者：若你的工具链为*.css、*.txt、*.svg等资源提供类型，可在 7.1 发布后为带属性的导入补充更精确的声明，利用"最具体优先"规则为不同属性提供不同类型。
2. 应用开发者：7.1 Beta 前仍需像以往一样自行编写或安装 ambient 声明；升级后可以验证属性感知的匹配是否修正了此前"所有模式导入共享同一类型"导致的误报。
3. 验证方式：在 7.1.0 Beta 及以上版本中，为同一 pattern 声明多份属性类型不同的 ambient 模块，再以对应属性导入，观察编译器是否选择最具体的声明——这是验证该特性落地的最直接手段。

来源与延伸阅读

• 本特性来源于 TypeScript 已合并的拉取请求Support import attributes on ambient modules（PR #63931），可在 TypeScript 官方仓库中查看完整讨论与测试用例。
• 关联阅读：others.md 的 Import Attributes 小节、exploring-the-type-system.md 的 Ambient Declarations 小节、TypeScript News 总览。

• 文档
• 教程