TypeScript 7.1 导入属性进入模式环境模块：按 `type: ‘css‘` 精确匹配模块类型-育师

文档
教程

【免费下载链接】typescript-book

The Concise TypeScript Book: A Concise Guide to Effective Development in TypeScript. Free and Open Source.

项目地址：https://gitcode.com/gh_mirrors/typ/typescript-book

TypeScript 7.1（原生编译器里程碑）为模式环境模块（pattern ambient module）声明新增了导入属性类型支持，使import style from './a.css' with { type: 'css' }这类带属性的导入能够被解析到属性类型相匹配的环境模块。读完本文，你将掌握该特性的匹配规则、最具体声明选择策略、声明合并规则、当前限制，以及在项目中为 CSS / 文本等资源定义属性感知类型声明的落地方法。

背景：两条已就绪的技术线

要理解这次改动，先回顾本特性依托的两块基础：环境模块声明与导入属性，它们分别对应 The Concise TypeScript Book 中的相关内容。

环境模块声明与模式匹配

环境模块声明（ambient module declaration）用于为没有类型信息的模块提供类型描述，典型的模式（pattern）形式如下：

declare module '*.css' { const content: string; export default content; }

*.css这类带通配符的模式声明，可以让所有import './x.css'命中同一份类型。仓库中 exploring-the-type-system.md 指出，lib.d.ts本身就包含大量常见 JavaScript 构造与 DOM 的环境声明——环境声明是整个类型系统"外部世界"边界的标准机制。运行环境无法解析的模块（CSS、文本、资源文件等），历来由项目方自行声明。

导入属性（Import Attributes）

导入属性自 TypeScript 5.3 起引入，是 import 语句上的"标签"，用于告知运行时如何处理该模块（JSON、CSS 等），并与 Content Security Policy（CSP）对齐。The Concise TypeScript Book 的 others.md 记录了两种写法：

静态导入：

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

动态导入：

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

在此之前，导入属性只由运行时解释，TypeScript 仅校验其合法性，不参与环境模块的区分与选择。

核心变化：环境模块声明可以携带属性类型

本次变更（对应 TypeScript 官方 PR《Support import attributes on ambient modules》，原始新闻见 typescript-7-1-import-attributes-ambient-modules.md）让模式环境模块声明本身可以声明导入属性类型，从而按属性区分导入。示意写法（语法细节以正式发布为准）：

// 声明示例：带属性类型的模式环境模块（示意） declare module '*.css' with { type: 'css' } { const css: string; export default css; } declare module '*.css' with { type: 'text' } { const text: string; export default text; }

于是import style from './a.css' with { type: 'css' }与import raw from './b.css' with { type: 'text' }可以解析到不同的类型声明——同样是*.css模式，属性不同则语义不同。这正是该特性要解决的场景：同一个扩展名模式对应多种导入语义（样式模块 vs 文本资源）时，类型不再混为一谈。

匹配规则：可赋值性 + 最具体者胜出

当 import 语句携带属性时，TypeScript 会尝试将该导入解析到匹配的模式环境模块。匹配遵循两条规则：

可赋值性匹配：import 声明的属性必须可赋值给环境模块声明的属性类型。例如with { type: 'css' }可以匹配声明了type: 'css'的环境模块。
最具体者优先：若多个声明同时匹配同一导入，TypeScript 会选择属性类型最具体的那个声明。

"最具体"意味着更窄的属性类型优先于更宽泛的类型。例如同一模式下同时存在声明type: 'css'与更泛化的type: string时，携带type: 'css'的导入会优先命中前者，使类型解析结果更精确、可预期。

合并与隔离规则

同一模式下存在多个声明时，合并行为取决于属性类型是否一致：

可以合并：模式相同且属性类型完全一致的声明，会像普通环境模块声明那样被合并（例如跨多个.d.ts文件对同一资源模块补充类型）。
保持独立：模式相同但属性类型不同的声明，彼此独立，各自解析对应的导入，不会相互污染或冲突。

该规则保证了"同模式多属性"场景下声明的正交性：CSS 语义与文本语义共存于*.css模式而不互相干扰。

当前限制与兼容性

属性类型限于字符串字面量

现阶段，环境模块声明上的属性类型仅支持普通属性且值为字符串字面量类型。也就是说可以声明type: 'css'、type: 'text'这样的精确标签，但不能声明嵌套对象、复杂结构或计算得到的类型。复杂属性的支持不在本次范围内。

标准库不内置声明

此改动不会向标准库添加任何 CSS 或文本导入的内置声明——即使你在项目中使用了with { type: 'css' }，TypeScript 也不会默认提供对应类型。项目和工具链仍须自行定义所需的环境模块（这正是环境模块机制的既有分工）。

版本与里程碑

该变更合入的是TypeScript 7.1.0 Beta里程碑。作为背景，TypeScript 7 是引入全新 Go 语言原生编译器与语言服务的重大版本，正如 typescript-news/index.md 所总结，7.0 已带来显著更快的构建与编辑器操作，而 7.1 的这项能力属于原生编译器持续推进的类型系统精细化工作。

实战建议：在项目中落地属性感知声明

结合 getting-started-with-typescript.md 的配置指引，落地路径如下：

确认版本：将 TypeScript 升级至 7.1.0 Beta 或更高（原生编译器里程碑）。
定义环境模块：在src/ambient.d.ts或types/目录中声明带属性类型的模式环境模块，覆盖项目实际使用的资源类型（CSS、文本、JSON 等）。
在导入处使用属性：静态或动态导入时附带with { type: '...' }，让类型解析按上述匹配规则命中正确的声明。
利用合并规则：将同一资源模块的补充类型分散到多个.d.ts时，保持属性类型完全一致以便合并；需要不同语义时使用不同属性类型保持独立。