React服务器构建报错：意外标记'<'（仅部署后出现）

本地开发环境运行完全正常，但服务器部署构建版本后出现报错：

Uncaught SyntaxError: Unexpected token '<' (at main.9ade8857.js:1:1)

简化代码示例 #

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <meta name="theme-color" content="#000000" />
    <title>React App</title>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

index.js

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

App.js

import './App.css';

function App() {
  return (
    <div className="App">
     <h1>Hosting Home Page</h1>
    </div>
  );
}

export default App;

问题原因 #

这个错误本质是浏览器请求JS/CSS静态资源时，服务器返回的不是对应的资源文件，而是HTML内容（比如首页index.html或404页面），浏览器把HTML当成JS解析，遇到第一个<就触发语法错误。常见诱因：

• 静态资源路径配置不匹配
• 服务器未正确配置静态资源目录
• SPA路由 fallback 规则缺失

解决方案 #

1. 配置package.json的homepage字段
   如果应用部署在域名子路径（如https://xxx.com/my-app），必须添加：

"homepage": "/my-app/"

根域名部署的话，设置为"homepage": "."或者直接删除该字段即可。

2. 修正服务器配置

• Nginx配置示例：

server {
  listen 80;
  server_name your-domain.com;
  root /path/to/your/build/folder;
  index index.html;

  # 缓存静态资源
  location /static/ {
    expires 30d;
    add_header Cache-Control "public, immutable";
  }

  # SPA路由兼容，非静态资源请求返回index.html
  location / {
    try_files $uri $uri/ /index.html;
  }
}

• Apache配置（确保启用mod_rewrite）：
  在build目录下创建.htaccess文件，内容如下：

Options -MultiViews
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.html [QSA,L]

3. 检查构建后的资源路径
   运行npm run build后，打开build/index.html，查看JS/CSS的引用路径是否和部署路径匹配。比如子路径部署的资源路径应该包含子目录，根部署则是根路径开头。如果路径错误，调整homepage后重新构建。

4. 确保构建文件完整上传
   重新执行npm run build，将整个build目录完整上传到服务器，不要遗漏任何子文件或子目录。

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