ECMAScript 导入属性特性详解

原文信息 📄 原文：Import Attributes in ECMAScript ✍️ 作者：Dr. Axel Rauschmayer 🔄 译者：Claude 3.5 Sonnet

概述

导入属性（Import Attributes）是 ECMAScript 的重要新特性，由 TC39 技术委员会推进，于 2024 年 10 月达到 Stage 4，预计成为 ECMAScript 2025 的正式组成部分。

核心价值

该特性主要解决 JavaScript 生态系统中导入非 JavaScript 资源的安全性和类型明确性问题，支持：

🔒 类型安全：明确指定导入资源的类型
🛡️ 安全防护：防止意外执行恶意代码
📝 代码文档化：让开发者意图更加清晰
🔧 工具支持：为构建工具和 IDE 提供更好的类型推断

提案贡献者

Sven Sauleau - 主要推动者
Daniel Ehrenberg - 技术设计
Myles Borins - 规范制定
Dan Clark - 浏览器实现
Nicolò Ribaudo - 工具链支持

历史背景

导入 JavaScript 模块（ESM）之外的资源

在 JavaScript 生态系统中，将非 JavaScript 代码作为模块导入由来已久。

例如，JavaScript 模块加载器 RequireJS 支持所谓的插件。为了让你了解 RequireJS 的历史悠久程度：版本 1.0.0 发布于 2009 年。通过插件导入的模块规范看起来是这样的：

"«specifier-of-plugin-module»!«specifier-of-artifact»";

例如，以下模块规范将文件作为 JSON 导入：

"json!./data/config.json";

受 RequireJS 启发，webpack 为其加载器支持相同的模块规范语法。

常见应用场景

现代 Web 开发中，非 JavaScript 资源导入的典型用例：

资源类型	应用场景	示例代码
JSON 数据	配置文件、静态数据、国际化文本	`import config from './config.json'`
CSS 样式	组件样式、主题配置	`import styles from './styles.css'`
WebAssembly	高性能计算、图像处理	`import wasmModule from './crypto.wasm'`
静态资源	图片、字体、音频文件	`import logo from './logo.png'`

技术挑战

传统解决方案存在的核心问题：

安全性风险

🚨 类型混淆：无法区分预期的 JSON 和恶意的 JavaScript
🔓 执行风险：错误配置可能导致意外代码执行

开发体验问题

❓ 意图不明：代码中无法清晰表达资源类型预期
🔧 工具支持：IDE 和类型检查器无法提供准确提示

标准化缺失

🏗️ 平台差异：不同构建工具语法不统一
📦 生态分裂：缺乏统一的标准规范

更多用例可以查看 webpack 加载器列表。

核心概念

导入属性（Import Attributes）是 ECMAScript 引入的新语法，用于明确指定导入资源的类型和处理方式。

基本原理

导入属性的主要用例是将 JSON 数据作为模块导入。具体如下（在单独的提案中有进一步说明）：

import configData from "./config-data.json" with { type: "json" };

为什么需要导入属性？

设计原则：内容类型优于文件扩展名

你可能会疑问：为什么不能直接使用文件扩展名 .json 来确定这是 JSON 数据？

这涉及到 Web 的核心架构原则：永远不要依赖文件扩展名来确定文件内容，而应该使用明确的内容类型声明。

安全性考虑

即使服务器配置正确，导入属性仍然必要：

风险场景	描述	导入属性的作用
恶意服务器	不受控制的外部服务器可能返回恶意 JavaScript	明确类型预期，防止代码执行
配置错误	服务器意外配置错误，返回错误的 MIME 类型	快速发现问题，提供明确反馈
代码意图	预期的内容类型在代码中不够明确	文档化程序员的预期和意图

实际案例

// 不安全：可能执行恶意代码
import data from "https://external-api.com/config.json";

// 安全：明确指定类型，拒绝非 JSON 内容
import data from "https://external-api.com/config.json" with { type: "json" };

语法规范

导入属性提供了三种主要的使用方式，覆盖了所有模块导入场景。

1. 静态导入语句

最常见的导入属性使用方式：

// 基本语法
import configData from "./config-data.json" with { type: "json" };

// 支持命名导入
import { userConfig, apiConfig } from "./config.json" with { type: "json" };

// 支持命名空间导入
import * as allConfig from "./config.json" with { type: "json" };

语法规则

导入属性的构成要素：

组成部分	规则	示例
关键字	固定使用 `with`	`with { ... }`
对象字面量	包含属性配置	`{ type: "json" }`
键名	支持引号和无引号	`type` 或 `"type"`
值	必须是字符串字面量	`"json"`, `"css"`

错误处理机制

导入属性采用严格验证策略：

✅ 支持的属性：正常处理导入
❌ 不支持的属性：立即抛出异常，而非忽略

设计理念：

🔒 安全优先：避免意外的运行时行为变化
🔮 前向兼容：为未来功能扩展预留空间

2. 动态导入

动态导入支持运行时条件加载，导入属性通过第二个参数进行配置：

// 基本动态导入语法
const configModule = await import("./config.json", {
  with: { type: "json" }
});

// 条件导入示例
async function loadConfig(environment) {
  const configPath = `./config-${environment}.json`;
  const config = await import(configPath, {
    with: { type: "json" }
  });
  return config.default;
}

// 错误处理
try {
  const data = await import("./data.json", {
    with: { type: "json" }
  });
  console.log(data.default);
} catch (error) {
  console.error("Failed to load JSON:", error);
}

配置对象结构

导入属性通过 with 属性嵌套配置，为未来扩展预留空间：

import(modulePath, {
  with: { type: "json" },        // 导入属性
  // 未来可能的其他配置选项
  // cache: "no-cache",
  // integrity: "sha256-..."
});

3. 重导出语句

重导出（re-export）实现导入和导出的一步操作，同样支持导入属性：

// 基本重导出
export { default as config } from "./config.json" with { type: "json" };

// 命名重导出
export { userSettings, apiSettings } from "./settings.json" with { type: "json" };

// 全部重导出
export * from "./constants.json" with { type: "json" };

// 重导出并重命名
export {
  default as defaultConfig,
  production as prodConfig
} from "./config.json" with { type: "json" };

应用场景

导入属性为各种资源类型的标准化导入奠定了语法基础。以下是基于该特性的主要应用场景和即将推出的功能。

1. JSON 模块导入

JSON 模块是导入属性的首个主要应用，已有专门提案推进：

// 配置文件导入
import config from "./app-config.json" with { type: "json" };

// 国际化数据
import translations from "./i18n/zh-CN.json" with { type: "json" };

// 静态数据集
import userData from "./mock/users.json" with { type: "json" };

// 使用导入的数据
console.log(config.apiUrl);
console.log(translations.welcome);

优势：

✅ 类型安全的 JSON 数据导入
✅ 编译时依赖分析
✅ 与模块系统无缝集成

2. CSS 模块导入

WHATWG 提案（Dan Clark 主导）支持构建时 CSS 处理：

// 组件样式导入
import styles from "./components/Button.css" with { type: "css" };

// 主题样式
import darkTheme from "./themes/dark.css" with { type: "css" };

// 应用样式
document.adoptedStyleSheets = [
  ...document.adoptedStyleSheets,
  styles,
  darkTheme
];

// 动态样式切换
function applyTheme(themeName) {
  import(`./themes/${themeName}.css`, { with: { type: "css" } })
    .then(theme => {
      document.adoptedStyleSheets = [styles, theme.default];
    });
}

3. WebAssembly 模块导入

WebAssembly 导入正在积极讨论中：

// 高性能计算模块
import wasmModule from "./crypto.wasm" with { type: "webassembly" };

// 图像处理
import imageProcessor from "./image-filters.wasm" with { type: "webassembly" };

// Web Worker 中使用
new Worker("./worker.wasm", {
  type: "module",
  with: { type: "webassembly" }
});

HTML 集成：

<script src="my-app.wasm" type="module" withtype="webassembly"></script>

4. 通用资源导入

其他资源类型的潜在支持：

// 文本文件
import readme from "./README.txt" with { type: "text" };

// 二进制数据
import binaryData from "./data.bin" with { type: "bytes" };

// 图片资源 URL
import logoUrl from "./assets/logo.png" with { type: "url" };

未来特性

导入属性的设计具有很强的前向兼容性，为未来功能扩展预留了充足空间。

1. 可选属性语法

提案考虑支持可忽略的属性语法（参考资料）：

// 可选属性语法（概念性）
import logo from "./logo.png" with {
  type: "image",
  "as?": "canvas"  // 问号表示可选
};

行为逻辑：

如果运行时支持 as 属性：

import logo from "./logo.png" with { type: "image", as: "canvas" };

如果不支持，则等价于：

import logo from "./logo.png" with { type: "image" };

2. 扩展的资源类型

Kris Kowal 提议的更多 type 值：

// 纯文本导入
import readme from "./README.txt" with { type: "text" };
// 返回：string

// 二进制数据导入
import data from "./data.bin" with { type: "bytes" };
// 返回：Uint8Array

// 资源 URL 导入
import imageUrl from "./logo.jpg" with { type: "url" };
// 返回：string (URL)

3. 高级配置选项

未来可能支持的更多配置：

// 缓存策略
import data from "./api/data.json" with {
  type: "json",
  cache: "no-cache"
};

// 完整性检查
import script from "./vendor/lib.js" with {
  type: "module",
};

// 条件导入
import polyfill from "./polyfills/modern.js" with {
  type: "module",
};

发展历程

导入属性提案历经 5 年发展，经历了多次重大变更和改进（详细历史）。

发展时间线

这个提案多年来经历了很多变化：

2019-12：提案的第一个版本语法略有不同，但支持多个属性：
```
import data from './data.json' with type: 'json';
```
2020-02：只允许一个属性，并包含在模块缓存键中：
```
import data from './data.json' as 'json';
```
2020-06：提案获得 Stage 2 批准，但支持多个属性，且属性不存储在模块缓存键中。

2020-07：关键字首先改名为 if，然后改为 assert：

import data from "./data.json" assert { type: "json" };

2020-09：提案获得 Stage 3 批准，断言存储在模块缓存键中。

之后，发现了两个问题：

术语"断言"意味着导入断言应该只影响模块是否被加载或评估，而不是如何加载。然而，在 Web 上，对资源的请求会根据其预期用途而改变：不同的 CSP 策略、不同的获取目标和接受的响应类型等。
类似地，导入断言不应该添加到模块缓存键中。

因此，在 2023 年 1 月，导入断言（关键字 assert）降级到 Stage 2，并获得了新名称"导入属性"（关键字 with）。

关键转折点

2023年的重大转向：

🔄 术语重定义："导入断言" → "导入属性"
🗝️ 关键字变更：assert → with
🎯 语义明确：从"验证"转向"指定"

最终里程碑：

✅ 2023年3月：Stage 3 - 规范稳定
🎉 2024年10月：Stage 4 - 正式成为 ECMAScript 2025

最佳实践

使用原则

✅ 明确类型：始终指定资源类型
🛡️ 安全优先：防止意外代码执行
📝 文档化：让代码意图更清晰
🔧 工具友好：支持构建工具和 IDE

ECMAScript 导入属性特性详解

On this page