UnoCSS Astro 在 Node 23 下报 ERR_UNSUPPORTED_ESM_URL_SCHEME一篇讲透原因与解法【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocssUnoCSS 65.5.0 及以上版本配合 Astro 使用时Windows Node.js 23 的组合会在启动瞬间炸出ERR_UNSUPPORTED_ESM_URL_SCHEMEdev server 直接起不来。先说结论这不是你的配置写错了而是 Node 23 默认开启 Type Stripping 后unconfig 用原生动态 import 加载uno.config.ts时Windows 盘符路径没被转换成file://URL。下面按真实排障顺序走一遍先给止血命令再拆根因最后讲彻底修复。一、现场还原同样的配置换个 Node 版本就死如果你也是这么中招的症状大概率长这样——配置没动、依赖没升 Node、只是把 Node 22 切到了 23astro dev一跑就抛错Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in: file, data, and node are supported by the default ESM loader. On Windows, absolute paths must be valid file:// URLs. Received protocol d:注意最后那句Received protocol d:。Node 的 ESM loader 把D:\path\to\uno.config.ts这种 Windows 绝对路径当成了协议为 d: 的 URL但它只认file、data、node三种 scheme。换句话说路径本身没写错错在有人把裸路径直接喂给了import()。二、先止血两条 30 秒生效的临时方案 急上线的话别研究原理先把服务跑起来。方案 A关掉 Node 23 的 Type Stripping。在package.json里给 dev 脚本加环境变量dev: NODE_OPTIONS--no-experimental-strip-types astro dev--no-experimental-strip-types让 Node 回退到旧行为UnoCSS 链路会重新走 jiti 编译配置绕开原生 import 的路径问题。小提醒VARvalue cmd是 POSIX 写法在 Windows 的 cmd / PowerShell 里建议配合cross-env或直接设置系统环境变量别指望这行原样能跑。方案 B项目根目录加一个.npmrcshell-emulatortrue这条让 npm 系工具用模拟器处理脚本环境同样能规避该链路在当前环境下的触发条件。两个方案都是关掉引爆开关不修雷本身。环境里还有别的依赖也在裸 import TypeScript 的话还会再炸一遍——所以继续往下看。三、为什么偏偏是 Node 23这是最多人困惑的点同样的 UnoCSS 版本Node 22 上安静得很23 上就报错。分水岭在于 Node 23 把实验性的 Type Stripping加载.ts文件时直接剥离类型后执行默认打开了。这条变化改变了 UnoCSS 配置加载的路由Node 23 之前uno.config.ts这类 TS 配置由jiti接管jiti 内部自己做了路径与模块格式的归一化Windows 盘符路径根本走不到 ESM loader 面前Node 23既然运行时自己能吃 TS 了unconfig检测到环境支持后改走原生动态import()。jiti 这道缓冲层被跳过D:\...这种裸路径第一次直面 ESM loader于是d:被当成协议名解析——报错就是这么来的。所以本质上是一次静默的路由切换Node 大版本升级没有改任何一行 UnoCSS 代码却把配置加载从兼容层托管切到了原生裸奔Windows 路径格式这个老雷就此引爆。相关加载入口可以对照 packages-engine/config/src/index.ts其中createConfigLoader来自unconfig真正出问题的是它内部的加载分支。四、根因拆解unconfig 动态 import 缺一步路径规范化 把链条摊开就三步UnoCSS 启动时通过unconfig定位并加载unocss.config.ts/uno.config.ts仓库里的 Astro 示例项目 里就能看到这个配置文件Node 23 下 unconfig 判定运行时支持直接吃 TS于是对配置路径执行import(file)传入的是 Windows 绝对路径而非 URL。按 Node 的 ESM 规范import()的参数必须是合法 URLWindows 下盘符路径必须先转成file:///D:/...形态典型实现是pathToFileURL()否则 loader 直接把盘符识别为 scheme抛ERR_UNSUPPORTED_ESM_URL_SCHEME。问题就出在第 2 步少做了一次路径规范化。这不是 Astro 的锅也不是 Vite 的锅——任何在 Node 23 上让 unconfig 加载 TS 配置的场景Vite、CLI 工具理论上都可能踩到只是 Astro 的astro dev启动链路最先撞上而已。五、彻底修复等 unconfig 的修复或主动锁版本根治方案在 unconfig 侧新版在动态 import 之前补上了路径规范化逻辑确保 Windows 绝对路径先被转换成合法的file://URL 再交给 loader。你可以被动等关注 UnoCSS 的后续发布升级后重新astro dev验证即可主动锁急用且不想赌发布节奏的话在package.json里用resolutionsYarn或overridesnpm字段把unconfig强制指到已修复的版本。修复上线后之前为止血加的NODE_OPTIONS和.npmrc配置记得撤掉让环境恢复干净。六、举一反三这类坑以后怎么防 跨平台项目里凡是要喂给import()的路径先过一遍pathToFileURL别假设字符串路径 可用 URL升级 Node 大版本后重点回归TS 配置加载这类场景因为 Type Stripping 这类默认行为变化会悄悄改写依赖内部的分支路由遇到ERR_UNSUPPORTED_ESM_URL_SCHEME这类 loader 级报错先看Received protocol后面跟的是什么——那是直接线索比翻堆栈快得多。收个尾这轮报错的链条是Node 23 默认 Type Stripping → unconfig 切原生动态 import → Windows 裸路径未转 file:// URL。先按第二节止血再等 unconfig 修复或锁版本收尾就能把坑彻底填平。【免费下载链接】unocssThe instant on-demand atomic CSS engine.项目地址: https://gitcode.com/GitHub_Trending/un/unocss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考