Skip to content

导入属性 ​

概览 ​

导入属性是导入语句中的 with { ... } 子句:

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

Node.js 和浏览器都要求使用 with { type: 'json' } 导入 JSON;浏览器还要求在 CSS 模块脚本中使用 with { type: 'css' }。为这些运行时编写的代码(包括依赖项)经常会使用这类导入。

启用 experimental.importAttributes 后,Rolldown 会将带有不同属性导入的同一文件视为不同模块。插件可以在 resolveId、load 和 transform 中读取属性,并在 resolveId 中修改属性。设计背景请参阅 RFC。

rolldown.config.js
js
import { defineConfig } from 'rolldown';

export default defineConfig({
  experimental: {
    importAttributes: true,
  },
});

实验性

experimental.importAttributes 默认关闭。启用后,带属性导入的模块 id 会发生变化。如果项目使用了自定义插件,请先阅读迁移插件,并查看限制。

支持的语法 ​

Rolldown 会读取静态导入、重新导出,以及带静态 with 对象的动态导入中的属性:

语法attributes
import x from 'a' with { type: 'json' }{ type: 'json' }
export * from 'a' with { type: 'json' }{ type: 'json' }
import('a', { with: { type: 'json' } }){ type: 'json' }
import x from 'a' assert { type: 'json' }{ type: 'json' }
import('a', options) where options is not a literal{}
require(), new URL(), CSS @import{}

Rolldown 会在构建时读取属性,因此 import() 选项必须直接写在调用中。如果选项来自变量(例如 import('./data.json', options)),Rolldown 就不会提取属性。

出于兼容性考虑,Rolldown 会将已移除的 assert 关键字视为 with,但未来会移除此语法支持。

工作原理 ​

模块 id ​

启用该选项后,导入属性会成为模块 id 的一部分。插件会为每个模块看到以下三个值:

值说明
rawId不含属性的已解析 id,即要读取和监听的文件。
attributesRecord<string, string> 类型的导入属性。{} 表示没有属性。
id由 rawId 和 attributes 组成的模块 id;没有属性时与 rawId 相同。

id 的格式为 rawId?attributes=<encoded attributes>。Rolldown 会按键名对属性排序,使用 JSON.stringify 序列化,再通过 encodeURIComponent 编码结果。如果 rawId 已经包含 ?,则使用 & 作为分隔符。

js
import config from './config.json' with { type: 'json' };
import small from './logo.png' with { size: '100' };
import large from './logo.png' with { size: '400' };
import original from './logo.png';
ImportrawIdattributesid
'./config.json' { type: 'json' }/src/config.json{ type: 'json' }/src/config.json?attributes=%7B%22type%22%3A%22json%22%7D
'./logo.png' { size: '100' }/src/logo.png{ size: '100' }/src/logo.png?attributes=%7B%22size%22%3A%22100%22%7D
'./logo.png' { size: '400' }/src/logo.png{ size: '400' }/src/logo.png?attributes=%7B%22size%22%3A%22400%22%7D
'./logo.png' (no attributes)/src/logo.png{}/src/logo.png (unchanged)

避免使用 ?attributes

不要在自定义 id 中将查询参数命名为 attributes。如果它的值恰好符合此格式,Rolldown 和 parseModuleId 就会将其解析为导入属性。

外部模块 ​

在 ESM 输出中,外部模块的导入会保留其属性,包括动态 import()。无论是否启用 experimental.importAttributes,这一点都成立。未启用该选项时,带属性导入的外部模块仍会在其模块 id 中保留这些属性,例如通过 this.getModuleIds() 获取时。

启用该选项后,resolveId hook 可以修改输出中的属性。如果 external 选项在解析前就将导入标记为外部模块,则不会运行 resolveId hook,导入会保留源代码中写入的属性。

关于 cjs、iife 和 umd 输出,请参阅非 ESM 输出格式。

内置的 type 属性 ​

启用该选项后,type 属性可以指定 Rolldown 的模块类型。常见情况无需插件即可处理:

属性模块类型默认导出
type: 'json'json解析后的 JSON
type: 'text'textstring
type: 'bytes'binaryUint8Array
js
import config from './config.json' with { type: 'json' };
import shader from './shader.glsl' with { type: 'text' };
import wasm from './module.wasm' with { type: 'bytes' };
import data from './data.txt' with { type: 'json' };

Rolldown 按以下优先级(从高到低)确定模块类型:

  1. load hook 返回的 moduleType。
  2. type 属性,其值为 json、text 或 bytes 时生效。
  3. 文件扩展名,包括 moduleTypes 选项中的映射。

其他 type 值(例如 'css')没有内置含义,会原样传递给插件。插件可以在 load hook 中处理这些值。

插件 API ​

未启用该选项时,以下字段仍然存在,但 attributes 始终为 {},且 resolveId 返回的 attributes 会被忽略。唯一的例外是对外部模块调用 this.resolve,它会返回该导入的属性。

resolveId ​

ts
resolveId(
  source: string,
  importer: string | undefined,
  extraOptions: {
    // ...
    // new: attributes of this import
    attributes: Record<string, string>;
    // new: `importer` without its attributes
    importerRawId: string | undefined;
    // new: attributes of the importer
    importerAttributes: Record<string, string>;
  },
): string | false | null | undefined | PartialResolvedId;

interface PartialResolvedId {
  // ...
  // new: replaces the attributes of the import
  attributes?: Record<string, string>;
}

由于 importer 包含导入方的属性,请使用 importerRawId 获取其文件路径。

返回 attributes 可以替换该导入的属性,返回 {} 则会移除属性。load 和 transform 无法修改这些属性。

例如,为外部 JSON 导入添加 Node.js 要求的属性:

js
resolveId(source) {
  if (source.endsWith('.json')) {
    return { id: source, external: true, attributes: { type: 'json' } };
  }
},
// input:  import pkg from '../package.json'
// output: import pkg from '../package.json' with { type: "json" };

注意

resolveDynamicImport hook 也会收到相同的新选项,并且同样可以返回 attributes。

load ​

ts
load(
  id: string,
  // new
  options: {
    // `id` without attributes
    rawId: string;
    // attributes of the module
    attributes: Record<string, string>;
  },
): LoadResult;

transform ​

ts
transform(
  code: string,
  id: string,
  meta: {
    // ...
    // new: `id` without attributes
    rawId: string;
    // new: attributes of the module
    attributes: Record<string, string>;
  },
): TransformResult;

this.resolve ​

ts
this.resolve(
  source: string,
  // changed: also accepts `{ rawId, attributes }`
  importer?: string | { rawId: string; attributes?: Record<string, string> },
  options?: {
    // ...
    // new: attributes of the simulated import
    attributes?: Record<string, string>;
  },
): Promise<ResolvedId | null>;

interface ResolvedId {
  // ...
  // without attributes
  id: string;
  // new: final attributes
  attributes: Record<string, string>;
}

this.load ​

ts
this.load(options: {
  // ...
  // changed: also accepts `{ rawId, attributes }`
  id: string | { rawId: string; attributes?: Record<string, string> };
}): Promise<ModuleInfo>;

属性只会从 id 获取。要加载带有属性的 this.resolve 结果,请将 { rawId: resolved.id, attributes: resolved.attributes } 作为 id 传入。

辅助函数 ​

只有 resolveId、load、transform、this.resolve 和 this.load 会提供 rawId 和 attributes。在其他位置,插件拿到的都是组合 id:

位置字段
this.getModuleInfo(), moduleParsedid, importedIds, importers, dynamicImporters
this.getModuleIds()返回的每个 id 都包含导入属性
Output chunks in renderChunk, generateBundlefacadeModuleId, moduleIds, the keys of modules
onLog, onwarnlog.id
选项回调,例如代码分割组的 test模块 id

可以使用 rolldown/utils 中的 parseModuleId 和 stringifyModuleId 处理这些 id:

ts
function parseModuleId(id: string): { rawId: string; attributes: Record<string, string> };
function stringifyModuleId(rawId: string, attributes?: Record<string, string>): string;
js
import { parseModuleId, stringifyModuleId } from 'rolldown/utils';

parseModuleId('/src/a.json?attributes=%7B%22type%22%3A%22json%22%7D');
// → { rawId: '/src/a.json', attributes: { type: 'json' } }

stringifyModuleId('/src/a.json', { type: 'json' });
// → '/src/a.json?attributes=%7B%22type%22%3A%22json%22%7D'

// warn about JSON files imported without `type: 'json'`
moduleParsed(info) {
  const { rawId, attributes } = parseModuleId(info.id);
  if (rawId.endsWith('.json') && attributes.type !== 'json') {
    this.warn(`${rawId} is imported without { type: 'json' }`);
  }
},

注意

output.paths、output.globals 和 treeshake.moduleSideEffects 接收的是 rawId,而不是组合 id。

迁移插件 ​

启用该选项后,将模块 id 当作文件路径处理的插件可能会失效。以下内容介绍常见情况及其修复方法。实际项目中,最常见的触发情况是在兼容 Node.js 的代码中导入 JSON,例如 import pkg from './package.json' with { type: 'json' }。

使用 rawId 读取文件 ​

id 末尾可能带有属性后缀,因此它不一定是文件路径。请使用 rawId 读取文件:

js
// before: fails with ENOENT for a module with attributes
load(id) {
  return fs.readFile(id, 'utf8');
}

// after
load(id, { rawId }) {
  return fs.readFile(rawId, 'utf8');
}

任何将 id 当作路径使用的代码都需要遵循同样的规则。path.extname(id) 会返回 .json?attributes=%7B...%7D,而 this.addWatchFile(id) 会监听一个并不存在的文件。由于属性中的 / 会被编码,path.dirname(id) 仍然可用。

匹配扩展名 ​

检查 id 的结尾永远无法匹配带属性的模块。请改为检查 rawId:

js
// before: never matches a module with attributes
transform(code, id) {
  if (!id.endsWith('.json')) return;
}

// after
transform(code, id, { rawId }) {
  if (!rawId.endsWith('.json')) return;
}

Hook 过滤器会匹配组合 id,因此将扩展名锚定在 id 末尾的过滤器将不再匹配。请允许出现查询后缀:

js
import { id, include, makeIdFiltersToMatchWithQuery } from '@rolldown/pluginutils';

// allow a query suffix by hand
filter: { id: /\.json($|\?)/ },

// `@rolldown/pluginutils` turns `/\.json$/` into `/\.json(?:\?.*)?$/`
filter: { id: makeIdFiltersToMatchWithQuery(/\.json$/) },

// composable filters: match the id with its query removed
filter: [include(id(/\.json$/, { cleanUrl: true }))],

对于 json 和 text,也可以改为按 moduleType 过滤。模块类型会在 transform 运行前确定,因此带有 type: 'json' 的导入此时模块类型已经是 json:

js
transform: {
  filter: { moduleType: 'json' },
  handler(code, id, { rawId, attributes }) {
    // ...
  },
}

这对 bytes 不适用。它的模块类型是 binary,而 transform 不会针对二进制模块运行。

使用 importerRawId 比较导入方 ​

如果导入方模块本身也是带属性导入的,importer 就是它的组合 id。例如,通过 with { type: 'css' } 导入的 CSS 文件中可以包含 @import。请使用 importerRawId 获取文件路径:

js
// before: `importer` may be `/src/style.css?attributes=...`
resolveId(source, importer) {
  if (!importer?.endsWith('.css')) return;
  // resolve `@import` and `url()` in CSS
}

// after
resolveId(source, importer, { importerRawId }) {
  if (!importerRawId?.endsWith('.css')) return;
  // ...
}

使用模块 id 作为状态键 ​

插件通常会从 resolveId 返回一个 id,并以它为键存储数据供 load 使用。如果导入带有属性,load 收到的 id 末尾会附带这些属性。由于带属性和不带属性的模块是不同模块,因此应使用完整模块 id 存储数据:

js
import { stringifyModuleId } from 'rolldown/utils';

const sources = new Map();

resolveId(source, importer, { attributes }) {
  if (source.startsWith('virtual:')) {
    const id = '\0' + source;
    sources.set(stringifyModuleId(id, attributes), buildSource(source, attributes));
    return id;
  }
},
load(id) {
  return sources.get(id);
},

转发 this.resolve 和 this.load 调用 ​

如果 resolveId hook 会将参数传递给 this.resolve,则无需修改。Rolldown 会自动从 importer 中读取属性:

js
resolveId(source, importer, options) {
  // importer: '/src/style.css?attributes=%7B%22type%22%3A%22css%22%7D'
  return this.resolve(source, importer, { ...options, skipSelf: true });
},

this.resolve 会在 attributes 字段中返回属性。this.load 只会从 id 中读取属性。因此,要加载带属性的模块,请将 { rawId, attributes } 作为 id 传入:

js
const resolved = await this.resolve('./data.js', importer, { attributes: { type: 'foo' } });
// resolved: { id: '/src/data.js', attributes: { type: 'foo' }, ... }
const info = await this.load({
  ...resolved,
  id: { rawId: resolved.id, attributes: resolved.attributes },
});
// info.id: '/src/data.js?attributes=%7B%22type%22%3A%22foo%22%7D'

未启用该选项时,resolved.attributes 为 {},info.id 为 /src/data.js。同一段代码在两种情况下都能正常工作。

检查魔法查询参数 ​

Vite 的 ?raw、?url 和 ?inline 等魔法查询参数会与属性共用查询字符串。同时使用两者的导入会在 id 中保留两者,因此将查询参数锚定在 id 末尾的检查将不再匹配:

js
// import svg from './icon.svg?raw' with { type: 'text' }
// id: '/src/icon.svg?raw&attributes=%7B%22type%22%3A%22text%22%7D'
id.endsWith('?raw'); // false
/[?&]raw\b/.test(id); // true

与 Rollup 5 的兼容性 ​

Rolldown 遵循 Rollup 5 的导入属性设计。本节假设已启用 experimental.importAttributes。模块 id 格式相同,因此同一模块在两个打包器中会获得相同的 id。新增 hook 字段、this.resolve 和 this.load 的行为一致,INVALID_IMPORT_ATTRIBUTE 也会在相同情况下报告。

差异:

  • Rolldown 为 type: 'json'、type: 'text' 和 type: 'bytes' 提供内置模块类型。Rollup 5 不会为任何属性赋予内置含义。
  • Rolldown 始终使用 with 渲染外部导入的属性。Rollup 5 可以通过 output.externalImportAttributes 丢弃这些属性,或通过已弃用的 output.importAttributesKey 使用 assert。
  • 对外部模块使用 import() 时,除非 resolveId hook 修改了属性,否则 Rolldown 会保留原样的选项。Rollup 5 则始终根据属性重新生成选项,因此会丢弃值来自变量的条目。
  • Rolldown 不支持 this.resolve() 中已弃用的 importerAttributes 选项。请改为将 importer 设为 { rawId, attributes }。

尚不支持:

  • ModuleInfo 和 RenderedModule 中的 rawId 与 attributes
  • chunk 中的 facadeModuleRawId 和 facadeModuleAttributes
  • external 函数的第四个参数,以及 output.globals 和 output.paths 函数中的 { attributes }
  • 当 output.globals 的对象形式为同一外部模块的多个属性变体指定相同全局名称时发出的 AMBIGUOUS_GLOBAL_NAME 警告
  • 使用 { rawId, attributes } 对象调用 this.getModuleInfo(),以及带属性的 this.emitFile() chunk
  • resolveFileUrl hook 中的 moduleRawId 和 moduleAttributes

限制 ​

  • Rolldown 的开发模式目前尚不支持。
  • Hook 过滤器目前无法匹配属性。请改为在 hook 中检查 attributes。
  • Vite 目前尚不支持此选项,其开发服务器和内置插件仍需更新。

Was this page helpful?