在 vite 项目中配置 esbuild，核心方法是修改 vite.config.js 文件中的 esbuild 字段。该配置对象支持 loader、jsxfactory、jsxfragment 和 define 等属性，用于控制编译器的加载器映射、jsx 转换方式以及全局常量替换。通过直接操作这些选项，可以精确调整 vite 底层对 esbuild 的调用行为。
如何配置 JSX 转换模式与加载器？
配置 JSX 转换模式和加载器需要设置 esbuild.jsxFactory、esbuild.jsxFragment 以及 esbuild.loader。将 jsxFactory 设为 h 并配合 jsxFragment 为 Fragment 可适配 Preact 或 React 旧版语法；使用 loader 可将特定后缀（如 .proto）映射为 text 或 json 以绕过默认解析限制。
// vite.config.js
export default {
esbuild: {
jsxFactory: 'h',
jsxFragment: 'Fragment',
loader: {
'.proto': 'text'
}
}
}上述代码展示了针对非标准 JSX 库和二进制文本文件的配置。当项目引入 Preact 时，默认的 React.createElement 调用会失效，此时必须显式指定工厂函数。对于 .proto 文件，ESBuild 默认无法处理，将其标记为 text 后，Vite 会将其作为纯字符串资源导入，从而避免模块解析错误。
立即学习“Java免费学习笔记（深入）”；
你是 TypeScript 项目架构专家，专注于脚手架搭建生产就绪的 Node.js 和前端应用。生成包含现代工具链（pnpm、Vite、Next.js）、类型
如何使用 define 注入全局常量？
使用 esbuild.define 可以在编译阶段向代码中注入全局常量，替代 process.env.NODE_ENV 或自定义变量。该属性接受一个键值对对象，键名会被原样替换为对应的字符串字面量。这种方式比 Vite 自带的 define 配置更贴近 ESBuild 原生行为，且能确保在 CSS 预处理前完成替换。
// vite.config.js
export default {
esbuild: {
define: {
'APP_VERSION': '"1.0.0"',
'DEBUG_MODE': 'true'
}
}
}在此配置下，源码中的 console.log(APP_VERSION) 会被直接转换为 console.log("1.0.0")。注意值必须是合法的 JavaScript 表达式字符串，例如数字需加引号包裹成字符串，布尔值可直接写 true。这种替换发生在 AST 解析阶段，因此不会影响运行时的作用域链。
当 define 注入的值包含特殊字符时会发生什么？
当 esbuild.define 注入的值包含未转义的双引号或换行符时，会导致编译报错或生成非法 JS 语法。ESBuild 要求 define 的值必须是有效的 JSON 或 JS 字面量字符串，若直接传入包含双引号的字符串而不进行二次转义，解析器会提前截断字符串。
// 错误示例
esbuild: {
define: {
'MSG': '"Hello World"' // 正确：外层单引号，内层双引号
}
}
// 潜在风险
esbuild: {
define: {
'MSG': 'He said "Hi"' // 错误：未转义内部双引号
}
}
在实际开发中，若需注入包含引号的复杂 JSON 字符串，应使用 JSON.stringify() 在构建脚本中预处理，或直接使用单引号包裹并转义内部双引号。ESBuild 不会自动处理此类边缘情况，开发者需确保传入的字符串在 JS 语法上是完全合法的。
