swc-plugin-compatibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SWC Plugin Compatibility

SWC插件兼容性

If you see errors like these during your build:

failed to invoke plugin on 'Some("/app/src/file.ts")'
failed to run Wasm plugin transform
RuntimeError: out of bounds memory access
LayoutError called Result::unwrap()

This is NOT a bug. You're using an incompatible version of

@lingui/swc-plugin

with your SWC runtime.

如果在构建过程中遇到以下错误：

failed to invoke plugin on 'Some("/app/src/file.ts")'
failed to run Wasm plugin transform
RuntimeError: out of bounds memory access
LayoutError called Result::unwrap()

这并非Bug。 你正在使用与SWC运行时不兼容的

@lingui/swc-plugin

版本。

Why This Happens

问题原因

SWC plugin support is experimental. The plugin API does not follow semantic versioning.

SWC uses Rkyv to transfer the AST between the core and plugins. Both must agree on the exact memory layout of the AST. If the layout changes (e.g., new ECMAScript features), older plugins cannot read the data correctly.

This layout cannot be negotiated at runtime - it must match at compile time.

SWC插件支持目前处于实验阶段，其插件API不遵循语义化版本规范。

SWC使用Rkyv在核心程序与插件之间传输AST（抽象语法树），两者必须完全匹配AST的内存布局。如果布局发生变化（例如新增ECMAScript特性），旧版本插件将无法正确读取数据。

这种布局无法在运行时协商，必须在编译时保持一致。

How to Fix

修复方法

Step 1: Check the Compatibility Table

步骤1：查看兼容性对照表

Go to the compatibility table and find the plugin version that matches your runtime.

访问兼容性对照表，找到与你的运行时匹配的插件版本。

Step 2: Use the Plugin Compatibility Site

步骤2：使用插件兼容性网站

For precise matching, use https://plugins.swc.rs/:

Select your runtime (e.g.,
```
next
```
)
Select your runtime version (e.g.,
```
next@15.0.1
```
)
Find a compatible
```
@lingui/swc-plugin
```
version

如需精准匹配，可访问https://plugins.swc.rs/：

选择你的运行时（例如
```
next
```
）
选择你的运行时版本（例如
```
next@15.0.1
```
）
找到兼容的
```
@lingui/swc-plugin
```
版本

Step 3: Pin Your Versions

步骤3：锁定版本

json

{
  "devDependencies": {
    "@lingui/swc-plugin": "5.10.0"
  }
}

Use an exact version (no

) to prevent accidental upgrades.

json

{
  "devDependencies": {
    "@lingui/swc-plugin": "5.10.0"
  }
}

使用精确版本（不要加

或

），防止意外升级。

Version Compatibility Quick Reference

版本兼容性速查

Plugin Version	@lingui/core	Notes
`5.*`	`@lingui/core@5.*`	Current
`4.*`	`@lingui/core@4.*`	Legacy

Important:

@lingui/swc-plugin

does not need to match other

@lingui/*

package versions exactly. It follows its own versioning scheme.

插件版本	@lingui/core	说明
`5.*`	`@lingui/core@5.*`	当前版本
`4.*`	`@lingui/core@4.*`	旧版本

重要提示：

@lingui/swc-plugin

无需与其他

@lingui/*

包版本完全匹配，它遵循独立的版本规范。

Rules to Avoid Build Breakage

避免构建失败的规则

Pin an exact plugin version compatible with your runtime
Don't auto-bump
@lingui/swc-plugin
- check release notes first
Don't auto-bump your runtime (Next.js, Rspack, etc.) - runtimes may bump
```
swc-core
```
in minor/patch releases
Check compatibility after any upgrade that touches SWC or the plugin

锁定与运行时兼容的精确插件版本
不要自动升级
@lingui/swc-plugin
- 先查看发布说明
不要自动升级运行时（Next.js、Rspack等）- 运行时可能在小版本/补丁版本中升级
```
swc-core
```
任何涉及SWC或插件的升级后，都要检查兼容性

Understanding Runtimes

关于运行时的说明

By "runtime" we mean the tool executing SWC: Next.js, Rspack, or

@swc/core

Some runtimes (like Next.js) embed SWC directly and don't use

@swc/core

from npm. This means:

You cannot control
```
swc-core
```
version via
```
package.json
```
Plugin compatibility depends on the runtime's embedded SWC version

这里的“运行时”指的是执行SWC的工具：Next.js、Rspack或

@swc/core

。

部分运行时（如Next.js）直接嵌入SWC，不使用npm中的

@swc/core

，这意味着：

你无法通过
```
package.json
```
控制
```
swc-core
```
版本
插件兼容性取决于运行时嵌入的SWC版本

Example: Next.js Configuration

示例：Next.js配置

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    swcPlugins: [
      ['@lingui/swc-plugin', {
        // Plugin options
      }],
    ],
  },
};

module.exports = nextConfig;

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    swcPlugins: [
      ['@lingui/swc-plugin', {
        // 插件选项
      }],
    ],
  },
};

module.exports = nextConfig;

Example: .swcrc Configuration

示例：.swcrc配置

json

{
  "$schema": "https://json.schemastore.org/swcrc",
  "jsc": {
    "experimental": {
      "plugins": [
        ["@lingui/swc-plugin", {}]
      ]
    }
  }
}

json

{
  "$schema": "https://json.schemastore.org/swcrc",
  "jsc": {
    "experimental": {
      "plugins": [
        ["@lingui/swc-plugin", {}]
      ]
    }
  }
}

What If No Compatible Version Exists?

无兼容版本时的处理

If your runtime uses a newer

swc-core

that no plugin version supports yet:

Check for recent plugin releases
Open an issue or PR at https://github.com/lingui/swc-plugin

如果你的运行时使用了新版本的

swc-core

，而目前没有插件版本支持：

查看插件的最新发布版本
在https://github.com/lingui/swc-plugin提交issue或PR