Vite 项目中因模块类型配置冲突导致的 CSS 插件模块解析失败问题解决指南-js教程-PHP中文网

Vite 项目中因模块类型配置冲突导致的 CSS 插件模块解析失败问题解决指南

本文详解如何解决 Vite + PostCSS 项目中因 package.json 的 "type": "module" 与配置文件扩展名不匹配，引发 Cannot find module X [plugin:vite:css] [postcss] 的典型报错。

本文详解如何解决 vite + postcss 项目中因 package.json 的 "type": "module" 与配置文件扩展名不匹配，引发 cannot find module x [plugin:vite:css] [postcss] 的典型报错。

在使用 Vite 构建现代前端项目时，尤其是集成 Tailwind CSS、Mantine 等依赖 PostCSS 的工具链时，开发者常遇到如下报错：

[plugin:vite:css] [postcss] Cannot find module './page'
Require stack:
  src/pages/index.ts

该错误看似指向路径导入问题（如 export { LoginPage } from './login/page'），但实际根源并非 TypeScript 或路径错误，而是 Vite 的 CSS 处理流程（通过 PostCSS 插件）在解析配置文件时发生了模块系统兼容性冲突。

? 根本原因分析

Vite 默认使用 ESM（ECMAScript Module）语义加载配置，但其内部 PostCSS 插件（如 vite:css）在某些场景下仍依赖 Node.js 的 CommonJS 加载机制。当你的 package.json 中显式声明：

{
  "type": "module"
}

Node.js 将强制所有 .js 文件按 ESM 解析。而你的 postcss.config.cjs 实际是 CommonJS 风格（module.exports = {...}），此时若文件扩展名仍为 .cjs 或 .js，Vite/PostCSS 在尝试动态 require() 该配置时会因模块类型不匹配而失败——尤其在 Windows 或某些 Node 版本下，该错误可能被错误地“投射”到业务代码的相对路径上（如 ./page），造成严重误导。

Vite

为开发、生产构建和库打包配置并优化 Vite。

下载

✅ 正确解决方案

只需两步，彻底消除模块解析歧义：

移除 package.json 中的 "type": "module" 字段
→ 让 Node.js 恢复默认的 CommonJS 模块解析行为，确保 PostCSS 配置可被正确 require。

将 PostCSS 配置文件重命名为 .mjs 扩展名，并保持 ESM 语法
若你希望保留 ESM 风格，应统一为：

// postcss.config.mjs
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
    'postcss-preset-mantine': {},
    'postcss-simple-vars': {
      variables: {
        'mantine-breakpoint-xs': '36em',
        'mantine-breakpoint-sm': '48em',
        'mantine-breakpoint-md': '62em',
        'mantine-breakpoint-lg': '75em',
        'mantine-breakpoint-xl': '88em',
      },
    },
  },
};

⚠️ 注意：.mjs 文件必须使用 export default（ESM），不可再用 module.exports（CommonJS）。

? 验证与补充建议

运行 npm run dev 前，执行 npx vite --version 确认 Vite 版本 ≥ 4.0（推荐 ≥ 5.0），以获得更稳定的 ESM/CommonJS 兼容性。
若项目中还存在 vite.config.js/ts，请确保其导出方式与 package.json#type 一致；启用 "type": "module" 时，vite.config.js 必须改为 vite.config.mjs 或 vite.config.ts（配合 TS 编译）。
不推荐混合使用 .cjs 配置 + "type": "module"，这是当前 Vite + PostCSS 生态中最常见的隐性陷阱。