无法生成PayloadCMS类型及importmaps，遇CSS文件扩展名错误

问题描述 #

使用PayloadCMS时，执行类型生成或配置importmaps操作时触发错误，系统提示与@payloadcms/ui依赖的CSS文件存在冲突，具体错误为Node.js无法识别.css文件扩展名，错误日志如下：

node:internal/process/promises:394
    triggerUncaughtException(err, true /* fromPromise */);
    ^
TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".css" for */node_modules/react-image-crop/dist/ReactCrop.css
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:219:9)
    at defaultGetFormat (node:internal/modules/esm/get_format:245:36)
    at defaultLoad (node:internal/modules/esm/load:120:22)
    at async nextLoad (node:internal/modules/esm/hooks:748:22)
    at async load (*/node_modules/payload/node_modules/tsx/dist/esm/index.mjs?1751835940762:2:1762)
    at async nextLoad (node:internal/modules/esm/hooks:748:22)
    at async Hooks.load (node:internal/modules/esm/hooks:385:20)
    at async handleMessage (node:internal/modules/esm/worker:199:18) {
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

Node.js v22.17.0

解决方案 #

1. 配置TypeScript排除CSS文件 #

修改项目根目录的tsconfig.json，添加排除规则，避免TypeScript尝试处理node_modules中的CSS文件：

{
  "compilerOptions": {
    // 保留原有编译配置
  },
  "exclude": [
    "node_modules/**/*.css",
    "build/**/*",
    "dist/**/*"
  ]
}

2. 调整tsx命令忽略CSS文件 #

如果使用tsx运行Payload脚本，在启动命令中添加--ignore "*.css"参数，让tsx跳过CSS文件的加载：

{
  "scripts": {
    "generate:types": "tsx --ignore \"*.css\" payload generate:types",
    "dev": "tsx --ignore \"*.css\" src/server.ts"
  }
}

3. 修正importmaps配置 #

检查payload.config.ts或相关配置文件中的import语句，确保没有直接导入第三方CSS文件。若需自定义UI样式，通过Payload官方支持的自定义CSS入口（如src/css/custom.css）引入，而非在配置文件中导入。

4. 降级Node.js版本（临时兼容方案） #

Node.js v22对ESM模块的文件扩展名校验更为严格，若上述方案无效，可降级至Node.js v20 LTS版本，该版本对这类兼容性问题处理更宽松。

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