React项目编译报意外字符'?'错误重启恢复的原因及预防方案

这个报错的核心是编译工具解析文件时，在代码开头读到了不属于手写内容的脏字符，和业务逻辑写法无关，结合重启编译器就恢复的现象，触发原因基本可以锁定在以下三类：

• 编译进程内存缓存错乱：开发模式下的热更新进程长期驻留时，文件监听模块（webpack的watchpack、vite依赖的chokidar等）在处理跨分区文件移动、编辑器临时文件覆盖、高频文件变更场景时，容易出现内存缓存和磁盘实际内容不一致的问题，会把文件读写过程中产生的标记位脏数据拼到读取到的文件内容最前面，刚好落在第一行import语句前，解析时就会抛出意外字符错误。这种场景下重启进程清空内存缓存，重新读取磁盘文件就会恢复正常，和你遇到的情况完全吻合。
• UTF-8 BOM头解析失败：如果新建文件时编辑器默认带BOM头（文件开头的三个不可见字节0xEF 0xBB 0xBF，用来标记文件编码），低版本的babel、webpack文件loader无法识别这三个字节，会将其解析为两个乱码?字符插在代码开头，也会报一模一样的错。但这类问题单纯重启编译器不会消失，必须修改文件编码才能解决。
• 编辑器插件异常写入：部分自动导入、代码格式化插件在版本不兼容、异常退出时，保存文件会错误插入不可见控制字符，这些字符在编辑视图下看不到，但编译阶段会被识别为乱码触发报错。

• 统一全项目文件编码：所有JS/TS/JSX/TSX代码文件统一使用无BOM的UTF-8编码保存，在编辑器底部状态栏即可查看当前文件编码，存量带BOM的文件可以直接通过编辑器的「以编码重新保存」功能批量修正。可以在项目根目录添加.editorconfig配置，强制所有新建文件符合编码规范，避免后续再出BOM问题：

root = true
[*.{js,jsx,ts,tsx,json,css}]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true

• 建立缓存排查的固定思路：开发进程不要连续运行数天不重启，遇到定位不到的语法错误，优先清理编译缓存再重启：
  • Create React App项目直接删除node_modules/.cache目录后再执行启动命令
  • Vite项目启动时加--force参数强制重跑依赖预构建
  • 自定义webpack项目可以在配置中关闭持久化缓存，或定期手动清理缓存目录
• 优化文件监听配置：如果是自定义webpack配置的项目，给watch选项增加聚合等待时间，等编辑器完全写完文件再触发重新编译，避免读到半写入的脏内容：

// webpack.config.js 配置片段
module.exports = {
  watchOptions: {
    aggregateTimeout: 300, // 文件变更后等待300ms再编译
    ignored: /node_modules/
  }
}

• 插件异常排查：如果同类问题频繁出现，检查近期更新过的编辑器插件，尤其是自动补全、格式化、自动导入类插件，临时禁用后验证是否复现，排除插件bug写入脏字符的可能。

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