React Query String本地正常生产环境404问题排查与解决

问题描述 #

React应用通过/profile?id=test123或/?profile=test123这类带查询参数的路由展示公共资料，使用useSearchParams()和useParams()实现逻辑，本地环境完全正常，但部署到生产环境后访问这类路由会重定向到404页面。

部署环境 #

• 服务器：Linode VPS（Debian系统）
• 反向代理：Nginx
• DNS：Cloudflare
• 构建方式：执行npm run build后将产物复制到/var/www/html

Nginx配置 #

server {
    listen 443;
    server_name domainname.com;

    root /var/www/html;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

相关代码 #

PublicProfile.jsx #

// PublicProfile.jsx
import { useEffect, useState } from 'react';
import { useSearchParams } from 'react-router-dom';
import { publicprofile } from '../../../../API/APIs';
import {
  Typography,
  List,
  ListItem,
  ListItemText,
  Divider,
  Box,
} from '@mui/material';

function PublicProfile() {
  let [searchParams, setSearchParams] = useSearchParams();
  console.log(searchParams);
  const logSearchParams = () => {
    console.log(searchParams.get("id"));
  };
  logSearchParams();
  const [school, setSchool] = useState(null);
  useEffect(() => {
    const fetchSchoolData = async () => {
      try {
        const payload = {
          query: searchParams.get("id"),
        };
        const response = await publicprofile(payload);

        if (!response.ok) {
          throw new Error('Failed to fetch school data');
        }
        const data = await response.json();
        setSchool(data);
        console.log(data);
      } catch (error) {
        console.error('Error fetching school data:', error);
      }
    };

    fetchSchoolData();
  }, [searchParams.get("id")]);

  if (!school) {
    return <div>Loading...</div>;
  }

  return (
    <Box p={2} border={1} borderRadius={4}>
      <Typography variant='h2'>{school.name}</Typography>

      <Box mt={2}>
        <Typography>
          <strong>Address:</strong> {school.address}
        </Typography>
      </Box>

      <Divider variant='middle' />

      <Box mt={2}>
        <List>
          <ListItem>
            <ListItemText
              primary={<strong>Phone:</strong>}
              secondary={school.contactDetails}
            />
          </ListItem>
        </List>
      </Box>

      <Divider variant='middle' />

      <Box mt={2}>
        <Typography>
          <strong>Established Date:</strong> {school.establishedDate}
        </Typography>
      </Box>

      <Divider variant='middle' />

      <Box mt={2}>
        <Typography>
          <strong>Facilities:</strong> {school.facilities.join(', ')}
        </Typography>
      </Box>
      {/* Add more details as needed */}
    </Box>
  );
}

export default PublicProfile;

Routes.js #

// Routes.js
<Route path='/' element={<Layout />}>
  <Route path='/' element={<LandingPage />} />
  <Route path='/register' element={<Register />} />
  <Route path='/login' element={<Login />} />
  <Route path='/forgotpassword' element={<ForgetPassword />} />
  <Route path='/validateOtp' element={<OTPValidation />} />
  <Route path='/resetpassword' element={<ResetPassword />} />
  <Route path='/profile' element={<PublicProfile />} />
</Route>
<Route path='/admin/' element={<AdminLayout />}>
  <Route path='/admin/profile' element={<AdminProfile />} />
  <Route path='/admin/school' element={<SchoolInfo />} />
  <Route
    path='/admin/createclassroom'
    element={<CreateClassroomForm />}
  />
  <Route
    path='/admin/generateInviteCode'
    element={<GenerateInviteCode />}
  />
  <Route path='/admin/createNewSchool' element={<CreateSchool />} />
  <Route path='/admin/attendance' element={<ViewAttendance />} />
</Route>

package.json #

{
  "name": "projectalpha",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "dependencies": {
"@emotion/react": "^11.11.4",
"@emotion/styled": "^11.11.5",
"@mui/material": "^5.15.15",
"@mui/x-data-grid": "^7.3.2",
"@reduxjs/toolkit": "^2.2.3",
"@tanstack/react-query": "^5.40.0",
"@tanstack/react-query-devtools": "^5.40.0",
"formik": "^2.4.5",
"html5-qrcode": "^2.3.8",
"logrocket": "^8.1.0",
"react": "^18.2.3",
"react-dom": "^18.2.0",
"react-redux": "^9.1.0",
"react-router-dom": "^6.22.3",
"react-table": "^7.8.0",
"styled-components": "^6.1.8"
  },
  "devDependencies": {
"@testing-library/dom": "^9.3.4",
"@testing-library/jest-dom": "^6.4.2",
"@testing-library/react": "^14.2.2",
"@types/react": "^18.2.56",
"@types/react-dom": "^18.2.19",
"@vitejs/plugin-react": "^4.2.1",
"eslint": "^8.56.0",
"eslint-plugin-react": "^7.33.2",
"eslint-plugin-react-hooks": "^4.6.0",
"eslint-plugin-react-refresh": "^0.4.5",
"vite": "^5.2.10",
"vitest": "^1.4.0"
  }
}

原因分析 #

1. Cloudflare配置干扰：Cloudflare的缓存规则或页面规则可能将带查询参数的请求误判为静态资源返回404；自动HTTPS重定向、缓存级别等功能也可能拦截路由。
2. Nginx配置细节遗漏：默认的try_files配置可能未正确传递查询参数到React应用，导致路由解析失败。
3. Vite构建路径问题：若vite.config.js中base路径设置错误，带参数的路由无法加载静态资源，间接引发404。
4. 路由逻辑一致性问题：/?profile=test123路由依赖LandingPage组件处理参数，生产环境可能存在逻辑不一致。

解决方案 #

1. 排查Cloudflare配置 #

• 临时切换Cloudflare到DNS only模式，直接访问服务器IP测试路由，确认是否是Cloudflare导致的问题。
• 添加页面规则匹配/profile*和/*?profile=*，设置缓存级别为“忽略查询字符串”，关闭可能影响路由的重定向规则。
• 检查SSL/TLS设置，确保为“灵活”或“严格”，避免HTTPS重定向丢失参数。

2. 优化Nginx配置 #

• 修改location /块，确保传递查询参数：

  location / {
      try_files $uri $uri/ /index.html$is_args$args;
  }
  

• 添加日志排查问题：

  access_log /var/log/nginx/react_access.log;
  error_log /var/log/nginx/react_error.log warn;
  

• 重启Nginx生效：sudo systemctl restart nginx

3. 确认Vite构建配置 #

• 在vite.config.js中确保base路径正确（根路径部署保持base: '/'，子路径部署修改为对应路径）：

  export default defineConfig({
    base: '/',
    // 其他配置...
  })
  

• 重新构建并部署：npm run build后重新复制产物到服务器。

4. 验证React Router配置 #

• 确保应用使用BrowserRouter：

  import { BrowserRouter } from 'react-router-dom';
  
  ReactDOM.createRoot(document.getElementById('root')).render(
    <BrowserRouter>
      <Routes />
    </BrowserRouter>
  );
  

• 检查LandingPage组件中处理profile查询参数的逻辑，确保与本地环境一致。

5. 测试与验证 #

• 访问目标路由，查看浏览器控制台是否有资源加载错误，确认查询参数是否被正确获取。
• 查看Nginx访问日志，确认请求是否到达服务器，以及index.html是否被正确返回。

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