React项目部署到韩国服务器后如何配置静态资源入口与前端路由
React项目部署到韩国服务器后,静态资源入口和前端路由是否正常,主要取决于构建产物路径、Nginx根目录以及SPA回退规则是否一致。服务器位于韩国不会改变React的路由机制,但需要同时确认域名解析、80/443端口、Nginx服务和构建环境可用。
以下方案以Ubuntu 22.04/24.04、Nginx、Vite或Create React App为例,应用部署在域名根路径,例如https://app.example.com/。目标是实现:访问根域名返回index.html,访问带哈希的JS/CSS文件返回真实静态文件,刷新/orders/1001等前端路由时仍返回React入口,而不是被Nginx直接判定为404。
一、确认部署结构和准备条件
1. 明确请求与文件的对应关系
建议先确定以下目录结构:
/var/www/react-app/
├── current -> /var/www/react-app/releases/20250101093000
├── releases/
│ ├── 20250101093000/
│ │ ├── index.html
│ │ ├── assets/
│ │ └── ...
│ └── 20250102101500/
└── previous -> /var/www/react-app/releases/20250101093000
Nginx中的root指向current,因此请求关系如下:
| 浏览器请求 | Nginx处理方式 | 服务器文件或结果 |
|---|---|---|
/ | 查找入口文件 | current/index.html |
/assets/index-abc123.js | 只查找真实文件 | current/assets/index-abc123.js |
/orders/1001 | 找不到真实文件后回退 | current/index.html |
/favicon.ico | 查找根目录文件 | current/favicon.ico |
/orders/1001是React Router的前端路由,不一定对应服务器上的目录。Nginx必须把这类请求交给index.html,再由React在浏览器中解析当前路径。
2. 检查服务器和域名
在韩国服务器上执行:
cat /etc/os-release
uname -m
sudo ss -lntp | grep -E ':(80|443)\b' || true
预期可以确认系统版本、CPU架构以及80或443端口是否已经被其他服务占用。若80端口被旧站点占用,不要直接停止未知服务,应先查看进程和服务名:
sudo ss -lntp
sudo systemctl --type=service --state=running
域名需要将A记录指向服务器IPv4地址。如果配置了AAAA记录,还要确认IPv6也确实指向可用服务,否则部分访问者可能通过IPv6进入另一台服务器或获得连接失败结果:
dig +short A app.example.com
dig +short AAAA app.example.com
如果DNS尚未生效,可以先使用本机回环地址和HTTP请求头测试Nginx,避免把DNS问题误判为React部署问题。
React静态站点的访问体验,也与承载它的服务器所在地和网络资源有关。A5idc数据提供韩国首尔物理服务器,配置涵盖不同CPU、存储和优化或国际线路方案,可用于部署面向韩国及周边用户的网站、前端静态资源和业务接口。结合Nginx提供静态文件访问与前端路由回退,可在同一服务器环境中承载React站点及相关业务服务。
3. 确认构建方式
生产环境不需要运行开发服务器,也不建议使用npm start作为静态站点的长期服务。React项目应先生成静态文件,再由Nginx提供访问。
部署前确认:
- 项目包含
package-lock.json、npm-shrinkwrap.json或其他锁定依赖文件; - 服务器Node.js版本符合
package.json中的engines要求; - 生产环境变量已经在构建前设置;
- 前端代码中没有直接写入数据库密码、服务器密钥等敏感信息;
- API地址、图片域名和资源前缀与正式域名一致。
二、调整静态资源入口
1. Vite项目
如果应用部署在域名根路径,Vite的base通常应为/。例如:
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
base: '/'
})
构建后通常会生成:
dist/
├── index.html
├── assets/
│ ├── index-abc123.js
│ └── index-def456.css
└── favicon.svg
如果项目原本配置了base: '/dev/'或其他路径,部署到域名根目录后仍会请求错误的资源地址,例如/dev/assets/index.js,页面就可能出现HTML可以访问但内容空白的情况。
2. Create React App项目
Create React App通常将产物放在build/目录,并把脚本放在static/目录。部署到域名根路径时,package.json不应保留不匹配的homepage:
{
"scripts": {
"build": "react-scripts build"
},
"homepage": "/"
}
如果没有配置homepage,通常也会按根路径构建。修改后必须重新执行构建,不能只替换Nginx配置。
3. 检查前端路由模式
使用BrowserRouter时,浏览器地址中会出现正常路径,例如:
/orders/1001
这种模式需要Nginx配置回退规则。使用HashRouter时,路径通常是:
/#/orders/1001
井号后的内容不会发送给Nginx,因此不需要同样的回退规则,但URL结构、SEO和服务端渲染配合方式不同。已经采用BrowserRouter的项目,通常不需要为了规避Nginx配置而临时改成HashRouter。
三、构建React项目并生成版本目录
可以在服务器构建,也可以在本地或CI中构建后只上传dist或build。服务器构建时,先准备Node.js环境并检查版本:
node -v
npm -v
版本应与项目开发或CI环境保持一致。确认源码已上传到/srv/react-app-src后执行:
cd /srv/react-app-src
npm ci
npm run build
npm ci要求项目存在锁定文件。如果项目没有锁定文件,应先在开发环境生成并提交,而不是在生产服务器上使用不受控的依赖版本。
Vite项目验证:
test -f /srv/react-app-src/dist/index.html
find /srv/react-app-src/dist -maxdepth 2 -type f | sort | head -n 20
Create React App项目验证:
test -f /srv/react-app-src/build/index.html
find /srv/react-app-src/build -maxdepth 2 -type f | sort | head -n 20
预期可以看到index.html以及JS、CSS、字体、图片等资源。继续检查入口中引用的路径:
grep -Eo '/(assets|static)/[^"]+\.(js|css)' \
/srv/react-app-src/dist/index.html | head
如果是Create React App,将命令中的dist/index.html替换为build/index.html。输出应类似:
/assets/index-abc123.js
/assets/index-def456.css
如果这里出现/dev/、http://127.0.0.1:3000/或开发环境域名,应先修正构建配置。
四、采用版本目录发布静态文件
版本目录可以避免直接覆盖正在提供服务的文件,也方便在异常时切回上一版。以下命令以Vite的dist目录为例,Create React App只需将BUILD_DIR改为/srv/react-app-src/build。
APP_ROOT=/var/www/react-app
BUILD_DIR=/srv/react-app-src/dist
RELEASE_ID=$(date -u +%Y%m%d%H%M%S)
RELEASE_DIR="$APP_ROOT/releases/$RELEASE_ID"
sudo install -d -m 755 "$APP_ROOT/releases"
sudo install -d -m 755 "$RELEASE_DIR"
sudo cp -a "$BUILD_DIR/." "$RELEASE_DIR/"
sudo find "$RELEASE_DIR" -type d -exec chmod 755 {} \;
sudo find "$RELEASE_DIR" -type f -exec chmod 644 {} \;
test -f "$RELEASE_DIR/index.html"
这些权限操作只作用于新版本目录,目的是确保Nginx的www-data用户可以读取文件。不要把权限调整范围写成整个/var/www,避免影响同机部署的其他站点。
记录当前版本,并以临时软链接完成切换:
OLD_RELEASE="$(readlink -f "$APP_ROOT/current" 2>/dev/null || true)"
if [ -n "$OLD_RELEASE" ]; then
sudo ln -s "$OLD_RELEASE" "$APP_ROOT/.previous-$RELEASE_ID"
sudo mv -Tf "$APP_ROOT/.previous-$RELEASE_ID" "$APP_ROOT/previous"
fi
sudo ln -s "$RELEASE_DIR" "$APP_ROOT/.current-$RELEASE_ID"
sudo mv -Tf "$APP_ROOT/.current-$RELEASE_ID" "$APP_ROOT/current"
readlink -f "$APP_ROOT/current"
test -f "$APP_ROOT/current/index.html"
预期最后两条命令分别输出新版本的绝对路径,并确认入口文件存在。若current原本是一个普通目录而不是软链接,不要强制覆盖,应先检查其内容并备份。
五、配置Nginx静态入口和SPA回退
创建站点配置文件:
sudo nano /etc/nginx/sites-available/react-app
域名根路径部署时,可以使用以下配置:
server {
listen 80;
listen [::]:80;
server_name app.example.com;
root /var/www/react-app/current;
index index.html;
# HTML入口不使用长期缓存,便于发布新版本后获取新的资源清单
location = /index.html {
try_files $uri =404;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Vite静态资源
location ^~ /assets/ {
try_files $uri =404;
add_header Cache-Control "public, max-age=2592000, immutable";
}
# Create React App静态资源
location ^~ /static/ {
try_files $uri =404;
add_header Cache-Control "public, max-age=2592000, immutable";
}
# 其他根目录文件,如favicon、manifest等
location = /favicon.ico {
try_files $uri =404;
}
location = /manifest.json {
try_files $uri =404;
add_header Cache-Control "no-cache";
}
# React BrowserRouter的前端路由回退
location / {
try_files $uri $uri/ /index.html;
}
}
这里有两个关键点:

/assets/和/static/只允许返回真实文件,找不到时返回404,不能回退到index.html。否则浏览器请求一个不存在的JS文件时,Nginx可能返回HTML,浏览器会报“模块加载失败”或MIME类型错误。- 普通路径使用
try_files $uri $uri/ /index.html。请求对应真实文件时直接返回文件;请求/orders/1001等不存在的服务器路径时,返回React入口。
只有文件名带内容哈希、发布后不会被覆盖的资源,才适合使用immutable。如果项目把未加哈希的公共图片或脚本放在assets目录中,应降低缓存时间,例如改为:
add_header Cache-Control "public, max-age=86400";
如果同一域名还提供/api/接口,需要为接口预留独立的Nginx规则,并放在SPA回退逻辑之前。否则接口路径发生错误时可能返回index.html,前端看到的不是JSON错误,而是一段HTML。
启用站点并检查配置:
sudo ln -s /etc/nginx/sites-available/react-app \
/etc/nginx/sites-enabled/react-app
sudo nginx -t
预期输出包含:
syntax is ok
test is successful
确认无误后重新加载Nginx:
sudo systemctl enable nginx
sudo systemctl reload nginx
sudo systemctl is-active nginx
reload只重新加载配置,不会停止现有连接。若nginx -t失败,不要执行reload,应根据报错行号修正配置。
六、处理部署在子路径的情况
如果应用不是部署在根域名,而是部署在https://app.example.com/app/,Vite的资源前缀必须改为:
export default defineConfig({
base: '/app/'
})
React Router需要设置:
<BrowserRouter basename="/app">
<App />
</BrowserRouter>
同时构建产物应放在版本目录的app子目录中:
/var/www/react-app/current/
└── app/
├── index.html
└── assets/
对应的Nginx片段如下:
root /var/www/react-app/current;
location = /app {
return 301 /app/;
}
location ^~ /app/assets/ {
try_files $uri =404;
add_header Cache-Control "public, max-age=2592000, immutable";
}
location ^~ /app/static/ {
try_files $uri =404;
add_header Cache-Control "public, max-age=2592000, immutable";
}
location /app/ {
try_files $uri $uri/ /app/index.html;
}
根路径部署和子路径部署不能只修改其中一项。base、basename、构建产物目录和Nginx回退地址必须保持一致。

七、逐项验证访问结果
1. 验证Nginx是否命中正确站点
DNS还未生效时,可以在服务器本机执行:
curl -I -H 'Host: app.example.com' http://127.0.0.1/
预期状态为200 OK,并且响应内容类型接近:
Content-Type: text/html
如果返回Nginx默认欢迎页,通常是server_name不匹配或默认站点优先级更高。可以查看完整生效配置:
sudo nginx -T | grep -n -A12 -B4 'server_name app.example.com'
2. 验证入口引用的静态资源
先从入口文件中复制一个实际资源路径,例如:
/assets/index-abc123.js
再请求:
curl -I http://127.0.0.1/assets/index-abc123.js \
-H 'Host: app.example.com'
预期状态为200 OK。如果资源不存在,应返回404,而不是返回index.html。这能确认静态资源入口和SPA回退没有互相干扰。
3. 验证前端路由刷新
执行:
curl -i http://127.0.0.1/orders/1001 \
-H 'Host: app.example.com'
预期状态为200 OK,响应正文是index.html内容。使用浏览器打开同一路径并刷新页面,地址应保持为/orders/1001,React应用应根据路由显示对应页面。
4. 验证缓存策略
curl -I http://127.0.0.1/ \
-H 'Host: app.example.com'
curl -I http://127.0.0.1/assets/index-abc123.js \
-H 'Host: app.example.com'
入口HTML应包含no-cache或相近策略,带哈希的静态资源应包含较长缓存时间。如果入口HTML被长期缓存,发布新版本后,用户可能继续拿到旧的资源清单。
八、常见异常与处理顺序
| 现象 | 常见原因 | 处理方法 |
|---|---|---|
| 根域名返回404 | Nginx根目录错误或没有入口文件 | 检查readlink -f /var/www/react-app/current和test -f .../index.html |
| 页面HTML正常但空白 | JS/CSS路径错误、构建环境变量错误或资源404 | 查看浏览器Network面板,检查入口中的/assets/、/static/路径 |
| 刷新前端路由返回404 | 缺少try_files ... /index.html | 检查location /是否存在SPA回退 |
| JS请求返回HTML | 静态资源location没有优先匹配 | 为/assets/或/static/增加try_files $uri =404 |
| 返回403 Forbidden | Nginx无法穿过目录或读取文件 | 使用namei -l /var/www/react-app/current/index.html检查每级目录权限 |
| 浏览器显示Nginx默认页 | 域名未命中目标server块 | 检查server_name、DNS以及是否存在默认站点 |
/api/返回HTML | API请求被SPA回退接管 | 为API路径配置独立规则,并确认接口上游状态 |
| 发布后仍加载旧页面 | HTML或CDN缓存过久 | 保持入口HTML不长期缓存,清理不匹配的缓存,并确认新旧资源文件名不同 |
查看Nginx日志时,优先从请求范围和时间入手:
sudo tail -n 100 /var/log/nginx/access.log
sudo tail -n 100 /var/log/nginx/error.log
如果日志中静态资源请求出现404,先确认文件是否存在,再检查Nginx配置,不要立即修改React路由代码:

find /var/www/react-app/current -maxdepth 3 -type f | sort | head -n 50
如果资源实际存在但仍返回403,重点检查目录遍历权限;如果文件不存在,则可能是构建路径、base配置或部署目录选择错误。
九、验收与回滚检查项
验收检查
上线前至少确认以下项目:
readlink -f /var/www/react-app/current指向本次发布目录;current/index.html存在且可以读取;- 根域名返回
200和HTML内容; - 入口HTML中引用的JS、CSS资源返回
200; /orders/1001等深层前端路由直接访问和刷新都返回React入口;- 不存在的静态资源返回404,而不是返回HTML;
- 入口HTML不使用长期缓存,带哈希资源使用长期缓存;
- 浏览器控制台没有资源404、MIME类型错误或混合内容错误;
- Nginx错误日志没有持续增加的权限错误;
- 如果配置了A和AAAA记录,IPv4、IPv6均能到达同一套站点。
回滚检查
发布过程中不要删除旧版本目录。若新版本出现白屏、路由异常或资源路径错误,可以切回previous:
APP_ROOT=/var/www/react-app
ROLLBACK_TARGET="$(readlink -f "$APP_ROOT/previous" 2>/dev/null || true)"
test -n "$ROLLBACK_TARGET"
test -f "$ROLLBACK_TARGET/index.html"
sudo ln -s "$ROLLBACK_TARGET" "$APP_ROOT/.current-rollback"
sudo mv -Tf "$APP_ROOT/.current-rollback" "$APP_ROOT/current"
sudo nginx -t && sudo systemctl reload nginx
readlink -f "$APP_ROOT/current"
回滚后重新验证根路径、静态资源和深层路由。该操作只切换静态文件版本,不会删除故障版本,便于后续比对构建产物和日志。
如果本次同时修改了Nginx配置,应先恢复配置备份,再执行配置检查:
sudo nginx -t
sudo systemctl reload nginx
只有确认旧版本页面、资源和路由均恢复后,才考虑清理不再需要的旧发布目录;清理操作应限定在明确的版本路径内,并保留至少一个可用回滚版本。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/8233.html



