Webpack 迁 Vite 踩坑记：一个让人抓狂的 Sourcemap 报错怎么破？

迁移 Vite，哪有那么丝滑？

最近团队在推进老项目的工程化升级，把祖传的 Webpack 往 Vite 上迁。看官方文档和各类博客的时候，总觉得"一键迁移"、"秒级启动"简直不要太爽。但真到了自己手里，各种历史包袱和自定义插件一上，该踩的坑一个都没少。

今天就来聊聊迁移过程中遇到的一个极其恶心、但又极其好解决的报错。如果你也在搞 Vite 迁移，或者在写自定义 Vite 插件，这篇短文大概率能帮你省下几个小时去搜 StackOverflow 的时间。

案发现场：阴魂不散的 Sourcemap 警告

项目跑起来后，终端里疯狂刷出这么一段黄灿灿的警告：

text 复制代码

Sourcemap is likely to be incorrect: a plugin (replaceLoader) was used to transform files, but didn't generate a sourcemap for the transformation. Consult the plugin documentation for help

看着这满屏的警告，强迫症真的受不了。虽然它只是个 warning，不阻塞编译，但每次热更新都弹一次，极其影响排查其他真正的错误。

报错信息里点名道姓地指出了罪魁祸首：replaceLoader。这是我们之前为了替换一些全局环境变量和特定字符串，自己写的一个简易 Webpack loader。在迁移 Vite 时，我顺手把它改成了 Vite 插件（本质上就是 Rollup 插件）。

顺藤摸瓜：Vite 为什么这么"矫情"？

在 Webpack 时代，loader 改了代码没给 sourcemap，Webpack 顶多就是 sourcemap 断点不准，很少会这么大声嚷嚷。但 Vite 底层在构建时用的是 Rollup，Rollup 对插件的规范性要求严格得多。

当你的插件在 transform 钩子里对源代码进行了修改（比如替换了字符串），Vite 就会默认你需要提供修改后的 Sourcemap，以便在浏览器里能正确映射到原始代码。如果你只返回了修改后的 code，却没给 map，Vite 就会认为你在"破坏"调试体验，于是疯狂抛出这个警告。

一行代码搞定：给 transform 加个 map: null

既然知道了 Vite 的脾气，解决起来就非常简单了。我们只需要在插件的 transform 钩子返回值里，显式地告诉 Vite："我确实改了代码，但我不想（或者没必要）生成 sourcemap，你闭嘴吧。"

怎么告诉它？加上 map: null 就行了。

来看看修改前后的代码对比：

修改前（疯狂报错）：

javascript 复制代码

export default function replaceLoader() {
  return {
    name: 'vite-plugin-replace-loader',
    transform(code, id) {
      if (!id.endsWith('.js') && !id.endsWith('.ts')) return null;
      
      // 简单的字符串替换逻辑
      const newCode = code.replace(/__APP_VERSION__/g, '"1.0.0"');
      
      // 只返回了 code，没管 map
      return { code: newCode }; 
    }
  };
}

修改后（世界清静了）：

javascript 复制代码

export default function replaceLoader() {
  return {
    name: 'vite-plugin-replace-loader',
    transform(code, id) {
      if (!id.endsWith('.js') && !id.endsWith('.ts')) return null;
      
      const newCode = code.replace(/__APP_VERSION__/g, '"1.0.0"');
      
      // 显式声明 map 为 null，消除警告
      return { 
        code: newCode, 
        map: null 
      }; 
    }
  };
}

加上 map: null 后，Vite 就知道你是故意不提供 sourcemap 的，警告瞬间消失，终端终于干净了。

避坑指南：写 Vite 插件的正确姿势

借着这个坑，顺便给大家提个醒。从 Webpack 转 Vite/Rollup 插件开发时，有几个细节一定要注意：

不要忽略返回值规范 ：Rollup 插件的钩子对返回值类型有严格要求。如果不需要修改，直接 return null 或 return undefined；如果修改了，必须返回包含 code 的对象，且最好带上 map。
善用 magic-string ：如果你真的需要精准的 sourcemap（比如写一个复杂的语法转换插件），别自己手搓 map 对象。强烈推荐使用 magic-string 这个库，它能在你修改字符串的同时，自动帮你生成完美的 sourcemap。
注意 enforce 属性 ：Vite 插件有 enforce: 'pre' | 'post' 的概念。如果你写的插件需要在代码被 Vue/React 编译器处理前执行，记得加上 enforce: 'pre'，否则你可能会拿到编译后的复杂代码，导致正则替换失效。

工程化迁移从来都不是简单的改改配置文件，底层的构建逻辑差异往往藏在这些不起眼的细节里。希望这个小小的填坑记录，能帮你少掉几根头发。