LinguiJS 在 Vite + TypeScript 项目中的宏编译问题解析

问题背景

LinguiJS 是一个优秀的国际化解决方案，它提供了强大的文本翻译功能。在使用 Vite 构建工具配合 TypeScript 开发时，开发者可能会遇到一个典型错误："The macro you imported from '@lingui/core/macro' is being executed outside the context of compilation"。这个错误表明 LinguiJS 的宏系统没有在正确的编译上下文中执行。

问题本质

这个问题的核心在于 Vite 的构建流程中，Babel 插件没有正确处理 TypeScript 文件中的宏调用。当开发者使用 t 宏进行国际化文本标记时，系统无法在编译阶段正确转换这些宏调用。

解决方案

1. 确保 Babel 插件正确配置

在 Vite 配置中，需要确保 vite-plugin-babel 能够处理 TypeScript 文件。默认情况下，这个插件可能只处理 JavaScript 文件。需要在插件配置中明确指定要处理的文件扩展名。

2. 检查构建脚本

开发过程中，一些预处理脚本可能会在不正确的上下文中执行宏调用。例如使用 tsx 直接执行包含宏的脚本，而不是通过 Vite 的构建流程。应该改用 vite-node 来执行这些脚本，确保宏能在正确的编译上下文中处理。

3. 完整的配置示例

一个完整的 Vite + TypeScript + LinguiJS 配置应该包含以下关键部分：

1. Vite 配置：确保包含 LinguiJS 插件和 Babel 插件，并正确配置 Babel 处理 TypeScript 文件
2. Babel 配置：需要包含 macros 插件来支持 LinguiJS 的宏系统
3. TypeScript 配置：确保编译器设置支持 LinguiJS 的类型系统

最佳实践

1. 始终通过 Vite 的构建流程来执行包含宏的代码
2. 在开发环境中，使用 vite-node 替代直接执行 TypeScript 文件
3. 定期检查构建工具的版本兼容性，特别是当升级 LinguiJS 主版本时
4. 在复杂的项目中，考虑将国际化相关代码集中管理，减少宏调用的分散度

总结

LinguiJS 在 Vite + TypeScript 项目中的宏编译问题通常源于构建流程的配置不当。通过正确配置 Babel 插件、使用适当的脚本执行方式以及遵循最佳实践，开发者可以充分利用 LinguiJS 的强大国际化功能，同时避免常见的编译问题。理解宏系统的工作原理和构建工具的交互方式，是解决这类问题的关键。