Next.js及CRA环境Source files失效无报错 source map无法正常调试

问题特征 #

• Next.js/CRA开发模式默认开启Source Map配置，但调试时无法看到可读源码，浏览器DevTools Sources面板仅展示编译后产物代码
• 全程无控制台报错，禁用全部浏览器扩展无改善，在Edge 94+webpack5、Chrome 96环境下问题稳定复现，Sources面板无对应source map资源记录

排查步骤（按优先级排序） #

浏览器侧基础配置校验 #

• 打开DevTools设置（DevTools界面按F1或点击右上角齿轮图标），确认已勾选Enable JavaScript source maps、Enable CSS source maps两个选项
• 进入Sources面板的Ignore List设置页，检查是否误将项目源码路径、webpack内部路径加入了忽略列表，若有则移除
• 清空站点全量缓存：进入Application面板 → Clear storage → 勾选所有缓存项点击Clear site data，重启本地dev服务后重试，旧缓存会导致source map引用地址失效

Next.js 场景专项修复 #

• 检查next.config.js配置，确认未强制关闭开发环境source map：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // productionBrowserSourceMaps仅影响生产构建，开发环境无需修改
  webpack: (config, { dev }) => {
    if (dev) {
      // 开发环境devtool不要设置为false/none，保持默认值eval-cheap-module-source-map即可
      config.devtool = 'eval-cheap-module-source-map'
    }
    return config
  }
}
module.exports = nextConfig

• 检查package.json里的dev启动脚本，确认next dev命令未携带--no-source-maps参数，该参数会直接禁用开发环境source map生成
• 检查项目根目录.env.development文件，确认不存在NEXT_DISABLE_SOURCEMAPS=true配置，该环境变量会强制关闭source map输出
• Next.js 13+版本如果开启了Turbo模式，早期Turbo版本存在source map兼容bug，临时用next dev --webpack切回webpack模式启动验证即可

CRA（Create React App）场景专项修复 #

• 检查.env.development文件，确认不存在GENERATE_SOURCEMAP=false配置，该配置会同时关闭开发、生产环境的source map生成
• 若已eject或使用react-app-rewired/craco自定义webpack配置，检查是否将devtool修改为了false/none等不生成source map的选项，开发环境需保持devtool为eval-cheap-module-source-map
• 使用craco的场景可参考以下配置修正：

module.exports = {
  webpack: {
    devtool: process.env.NODE_ENV === 'development' ? 'eval-cheap-module-source-map' : undefined
  }
}

通用兜底排查 #

• 打开DevTools Network面板，筛选.map后缀请求，检查是否存在404/500加载失败：若存在.map资源404，一般是webpack的output.devtoolModuleFilenameTemplate配置错误导致路径不匹配，修正对应配置即可
• 临时关闭系统代理、VPN、抓包工具（Charles、Fiddler等）后重试，部分代理规则会默认拦截.map后缀资源，导致浏览器无法加载source map
• 检查项目内webpack插件配置，开发环境下临时禁用代码压缩、模块转换类插件后重试，部分第三方插件会破坏source map的生成链路

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