企业官网建设流程全解析

• 文档
• 教程

导读：TypeScript 7.1 开始，原生编译器支持在 pattern ambient module 声明中为 import attributes 提供类型信息，允许通过type: 'css'、type: 'text'等属性区分不同类型的 import。本文将结合《The Concise TypeScript Book》中关于 ambient declarations 与 import attributes 的讲解，深入剖析该特性的匹配规则、合并行为、兼容性边界，并给出可直接落地的.d.ts声明示例。

公开日：2026年9月1日

背景：import attributes 与 ambient module 的由来

什么是 import attributes

import attributes（导入属性）是 ES 模块规范中的一项能力，用于给 import 语句附加运行时如何解释模块的提示信息。它最典型的场景是导入 JSON 等非 JavaScript 模块：

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

动态导入同样支持携带属性：

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

正如《The Concise TypeScript Book》在 Import Attributes 一节 中所总结的：TypeScript 负责校验这些属性在语法与类型上是否合法，而具体的解释交给运行时（例如 Node.js 的模块加载器）。这一机制也契合 Content Security Policy（CSP）对资源加载的安全性要求——明确的导入声明让代码审计与权限控制更加清晰。

什么是 ambient module 声明

ambient 声明（Ambient Declarations）是指.d.ts声明文件中用于描述既有 JavaScript 代码类型的信息。声明文件不包含实现，仅提供类型占位，通常用于为现有 JS 库补充类型、或在// @ts-check的 JavaScript 文件中启用类型提示。

针对「无类型模块」这一场景，TypeScript 提供了 pattern ambient module 声明，即使用通配符的declare module：

declare module "*.css"; declare module "*.text" { ... }

在旧版本 TypeScript 中，这类声明只能描述「该模块存在以及它导出什么」，无法基于 import 携带的属性（如type: 'css'）进一步区分不同类型的导入。这正是 TypeScript 7.1 所要解决的问题。

核心变更：属性感知的 ambient module 匹配

TypeScript 7.1 的原生编译器新增了对 pattern ambient module 声明中 import attributes 的类型支持。当 import 语句带有属性时，TypeScript 会依据这些属性去解析匹配的 pattern ambient module 声明，而不是仅仅按模块路径通配符匹配。

以type: 'css'为例：

declare module "*.css" { const styles: CSSModule; export default styles; }

配合使用：

import styles from "./app.css" with { type: "css" };

在这一版本之前，即使声明存在，with { type: "css" }也无法被当作匹配依据；而现在编译器可以据此将导入解析到带type: 'css'属性类型的声明上。

匹配规则：基于赋值相容性（assignability）

匹配过程使用的是**赋值相容性（assignability）**检查：import 中实际提供的属性值，必须能够赋给声明中所标注的属性类型。

例如声明：

declare module "*.css" { // 属性类型为字符串字面量类型 'css' }

其中属性的类型被限定为字符串字面量类型（string literal type）的普通属性——这是当前版本（7.1）下的一种刻意约束：属性类型只能是形如type: 'css'这类字面量，不能是宽泛的string、联合类型或更复杂的对象类型。这种限定让匹配具备精确性与可预测性，也保证了声明文件作者的意图不会被任意字符串值击穿。

多声明并存时的选择策略

当多个 pattern ambient module 声明同时匹配同一个导入时，TypeScript 会采用「最具体」原则：

• 能基于属性类型实现匹配的声明优先于仅靠路径通配符匹配的声明；
• 在多个声明均能匹配的情况下，选择具有最具体属性类型（most specific attribute type）的声明。

这保证了你可以同时存在通用回退声明与针对特定属性的声明，例如：

declare module "*.css" { // 通用声明（回退用） } declare module "*.css" { const cssText: string; export default cssText; // 仅当 import 带 with { type: 'css' } 时命中 }

编译器会依据 import 是否携带type: 'css'属性，在两者之间做出符合预期的选择。

合并规则：相同即合并，不同即分治

该特性对声明的「合并（merging）」行为也做了明确定义：

• 相同 pattern 且属性类型完全相同的声明，可以像普通 ambient module 一样被合并（declaration merging），最终类型是各声明导出的叠加；
• 属性类型不同的声明则被视为彼此独立的声明，分别处理，互不合并。

换言之，属性类型成为声明合并中的一个关键维度：*.css（带type: 'css'）与*.css（带type: 'text'）是两份独立声明，各自拥有独立的导出类型空间，而不是被粗暴合并导致类型互相污染。

兼容性与版本边界

• 该特性面向TypeScript 7.1.0 Beta 里程碑合并，7.1 之前的版本（包括 7.0）不支持在 ambient module 声明中书写属性类型。
• 需要特别强调的是：TypeScript 标准库（lib）并不会因此内置任何 CSS 或文本导入的 ambient module 声明。也就是说，标准库不会替你声明*.css、*.text等模块——项目与工具链仍然需要像过去一样，自行定义所需的 ambient module 声明，只是现在这些声明可以描述 import attributes 的类型。
• 运行时行为不受影响：属性最终如何被模块加载器解释（例如 Node.js 是否原生支持type: 'css'），仍由运行环境决定，TypeScript 只负责静态类型层面的校验与解析。

实战落地：为 CSS/文本导入编写属性感知的声明

结合本书 Ambient Declarations 一节的指引（声明文件位于.d.ts，可用三斜线指令引入）：

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

在types/ambient-modules.d.ts中编写：

// 通用回退：未携带属性的 *.css 导入 declare module "*.css"; // 属性感知：携带 with { type: 'css' } 的导入 declare module "*.css" { const css: { [className: string]: string }; export default css; } // 文本导入：携带 with { type: 'text' } 的导入 declare module "*.text" { const text: string; export default text; }

对应源码侧的使用：

import cssModule from "./styles.css" with { type: "css" }; import readme from "./README.text" with { type: "text" };

此时cssModule会被解析为{ [className: string]: string }类型，readme被解析为string——这正是 7.1 之前无法通过 ambient 声明精确表达的类型信息。

小结

TypeScript 7.1 将 import attributes 纳入 pattern ambient module 的类型匹配体系，为 CSS、文本等非 JS 模块导入提供了精确的声明能力：

• 匹配基于赋值相容性，多声明并存时选择属性类型最具体者；
• 相同 pattern + 相同属性类型可合并，不同属性类型则独立处理；
• 属性类型当前限定为字符串字面量类型的普通属性；
• 面向7.1.0 Beta里程碑，且标准库不内置CSS/文本声明，仍需项目自行定义 ambient module。

对于正在建设模块化前端工程、需要为样式与资源导入建立严谨类型边界的团队而言，这一特性让.d.ts声明从「存在性证明」升级为「按属性精确描述类型」，值得在升级 TypeScript 7.1 后立即采用。

• 文档
• 教程