intlayerPrune Vite 插件文档

intlayerPrune Vite 插件用于对应用包中未使用的字典进行 tree-shaking 和裁剪。这样可以通过仅包含必要的多语言内容来减小最终包的体积。

使用

作为 intlayer() 的一部分（推荐）

通过您的 Intlayer 配置启用剪枝，主插件会处理一切：

// intlayer.config.tsimport { defineConfig } from "intlayer";export default defineConfig({  build: {    optimize: true, // 启用剪枝和最小化  },});

// vite.config.tsimport { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

独立使用

如果您是手动组合插件堆栈，intlayerPrune 和 intlayerMinify 共享一个 PruneContext 对象，该对象必须创建一次并传递给两者：

// vite.config.tsimport { defineConfig } from "vite";import { intlayerPrune, intlayerMinify } from "vite-intlayer";import { createPruneContext } from "@intlayer/babel";import { getConfiguration } from "@intlayer/config/node";const intlayerConfig = getConfiguration();const pruneContext = createPruneContext();export default defineConfig({  plugins: [    intlayerPrune(intlayerConfig, pruneContext),    intlayerMinify(intlayerConfig, pruneContext), // 可选，从同一上下文读取  ],});

它的工作原理

1. 使用情况分析 (buildStart)

在 buildStart 期间，intlayerOptimize 插件（也是 intlayer() 的一部分）扫描 build.filesList 中列出的每个组件源文件。对于每个 useIntlayer('key') 或 getIntlayer('key') 调用，它会准确记录访问了哪些字段，例如：

const { title, description } = useIntlayer("myDict");// 记录: myDict → { title, description }

这在任何 transform 调用运行之前建立了 pruneContext.fieldUsageMap。

2. JSON 修剪 (transform, enforce: 'pre')

当 Vite 处理编译的字典 JSON 文件时，intlayerPrune 在 Vite 的内置 JSON → ESM 转换之前拦截它。它从 pruneContext 读取字段使用情况映射，并删除任何不在记录的使用集中的内容字段。

支持两种内容形状：

• 静态字典 — { nodeType: "translation", translation: { en: {...}, fr: {...} } }。字段在 translation 内按语言环境修剪。
• 动态（按语言环境）字典 — 扁平化 { fieldA: ..., fieldB: ... }。字段在顶级进行修剪。

3. Edge cases

如果字典的内容结构无法识别（例如，不寻常的嵌套形状），它会被添加到 pruneContext.dictionariesWithEdgeCases 中并保持不变。会记录一条警告。intlayerMinify 也会跳过这些字典。

4. Field-rename map

当剪枝成功时，intlayerPrune 也会写入 pruneContext.dictionaryKeyToFieldRenameMap — 一个从原始字段名到简短别名的映射。intlayerMinify 读取此映射以在输出 JSON 中重命名字段，而 intlayerOptimize 的 Babel 重命名传递相应地更新源文件中的属性访问。

激活条件

intlayerPrune 仅当以下所有条件都为真时才会激活：

1. Vite 命令是 build。
2. build.optimize 是 true（或 undefined，在构建时默认为 true）。
3. 在您的 Intlayer 配置中 build.purge 是 true。

当 editor.enabled 是 true 时，它会自动禁用，因为编辑器需要完整的字典内容。