React生产部署出现SyntaxError: Unexpected token '<'问题求助

这个错误的核心原因是：浏览器缓存了旧的index.html或静态资源，新部署后旧入口文件引用的哈希命名资源已被替换，服务器返回404时默认返回index.html内容，浏览器把HTML当成JS解析就抛出该错误。以下是具体解决方法：

1. 确保CRA的资源哈希命名生效 #

你当前使用的react-scripts build（或build:prod）命令默认会给所有静态资源（JS/CSS/图片等）添加内容哈希（比如main.abc123.js），新构建的资源文件名会和旧版本完全不同，这一步已经没问题，部署时确保替换所有旧的静态资源文件即可。

2. 配置服务器缓存策略（关键） #

通过服务器规则区分入口文件和静态资源的缓存逻辑：

• index.html：设置禁止缓存或极短缓存时间，确保每次请求都获取最新版本
• 哈希命名的静态资源：设置长期缓存，因为文件名变更才会触发更新，不会出现缓存冲突

以Nginx为例，配置示例：

# 入口文件禁止缓存
location = /index.html {
    expires -1;
    add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate";
}

# 静态资源长期缓存（1年）
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

其他服务器（Apache/Netlify/Vercel等）可对应设置类似规则，比如Netlify会自动处理静态资源的哈希缓存，只需确保index.html的缓存策略为no-cache。

3. 添加版本检测的兜底方案 #

在应用初始化时检测版本更新，自动触发刷新：

1. 在构建目录（build）中创建version.json文件，内容为：

   {"version": "1.0.1"}
   

   每次部署时更新这个版本号。

2. 在App.tsx中添加版本检测逻辑：

   useEffect(() => {
     fetch('/version.json')
       .then(res => res.json())
       .then(data => {
         const savedVersion = localStorage.getItem('appVersion');
         if (savedVersion !== data.version) {
           localStorage.setItem('appVersion', data.version);
           window.location.reload(true); // 强制刷新，忽略缓存
         }
       })
       .catch(err => console.error('版本检测失败:', err));
   }, []);
   

   这样用户打开应用时会自动检测版本，如有更新则强制刷新，无需手动操作。

4. 检查SPA路由配置 #

如果使用React Router，确保服务器配置了SPA fallback：所有路由请求都返回index.html，避免路由跳转时出现404，但这一步需配合缓存策略一起使用，防止旧index.html被缓存。

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