使用esbuild时无法解析Blueprint.js等CSS文件的@import导入问题

问题场景 #

未使用Webpack，在CSS文件中通过@import导入Blueprint.js相关CSS时，路径解析失败。

CSS导入语句 #

@import "~normalize.css";
@import "~@blueprintjs/core/lib/css/blueprint.css";
@import "~@blueprintjs/icons/lib/css/blueprint-icons.css";

构建错误信息 #

Error: Build failed with 3 errors:
src/style.css:2:8: error: Could not resolve "~normalize.css" (mark it as external to exclude it from the bundle)
src/style.css:3:8: error: Could not resolve "~@blueprintjs/core/lib/css/blueprint.css" (mark it as external to exclude it from the bundle)
src/style.css:4:8: error: Could not resolve "~@blueprintjs/icons/lib/css/blueprint-icons.css" (mark it as external to exclude it from the bundle)

当前Builder.js配置 #

const { start } = require('live-server')
const { watch } = require('chokidar')
const { build } = require('esbuild')
const fs = require('fs-extra')

const isDev = process.env.NODE_ENV !== 'production'

/**
 * Live Server Params
 */
const serverParams = {
  port: 8000,
  root: 'dist',
  open: true
}

/**
 * ESBuild Params
 */
const buildParams = {
  color: true,
  entryPoints: ['src/index.jsx'],
  loader: { '.js': 'jsx' },
  outdir: 'dist',
  minify: !isDev,
  format: 'cjs',
  bundle: true,
  sourcemap: true,
  logLevel: 'error',
  incremental: true
}
;(async () => {
  fs.removeSync('dist')
  fs.copySync('public', 'dist')
  const builder = await build(buildParams)

  if (isDev) {
    watch('src/**/*', { ignoreInitial: true }).on('all', () => {
      builder.rebuild()
    })

    start(serverParams)
  } else {
    process.exit(0)
  }
})()

解决方案 #

1. 移除CSS导入中的~前缀 #

~是Webpack特有的路径前缀语法，ESBuild不支持该写法。ESBuild会自动从node_modules目录查找依赖包，直接修改CSS导入语句：

@import "normalize.css";
@import "@blueprintjs/core/lib/css/blueprint.css";
@import "@blueprintjs/icons/lib/css/blueprint-icons.css";

2. 配置ESBuild支持CSS解析 #

当前配置未添加CSS文件的处理规则，需要在buildParams中补充CSS loader，并确保入口JS文件导入CSS。

2.1 更新ESBuild的loader配置

修改buildParams里的loader字段，添加.css的处理规则：

const buildParams = {
  color: true,
  entryPoints: ['src/index.jsx'],
  loader: { 
    '.js': 'jsx',
    '.css': 'css' // 新增：让ESBuild识别并解析CSS文件
  },
  outdir: 'dist',
  minify: !isDev,
  format: 'cjs',
  bundle: true,
  sourcemap: true,
  logLevel: 'error',
  incremental: true
}

2.2 在入口JS中导入CSS文件

在src/index.jsx的顶部添加CSS导入，确保ESBuild能将CSS纳入构建流程：

import './style.css';

可选：提取独立CSS文件（非内联） #

如果不想将CSS内联到JS中，而是生成单独的.css文件，可以使用ESBuild插件实现：

1. 安装插件：

npm install esbuild-plugin-css-bundle --save-dev

2. 在Builder.js中引入并配置插件：

const cssBundlePlugin = require('esbuild-plugin-css-bundle');

const buildParams = {
  // 保留原有配置...
  plugins: [cssBundlePlugin()] // 新增插件配置
}

完成以上修改后，重新执行构建命令即可解决路径解析问题。

内容的提问来源于stack exchange，提问作者JJWALLACE