React项目部署到韩国服务器后如何配置静态资源入口与前端路由

发布人:A5数据发布时间:2026-11-08 11:19阅读量:83

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;
    }
}

这里有两个关键点:

五、配置Nginx静态入口和SPA回退配图

  1. /assets/和/static/只允许返回真实文件,找不到时返回404,不能回退到index.html。否则浏览器请求一个不存在的JS文件时,Nginx可能返回HTML,浏览器会报“模块加载失败”或MIME类型错误。
  2. 普通路径使用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被长期缓存,发布新版本后,用户可能继续拿到旧的资源清单。

八、常见异常与处理顺序

现象常见原因处理方法
根域名返回404Nginx根目录错误或没有入口文件检查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 ForbiddenNginx无法穿过目录或读取文件使用namei -l /var/www/react-app/current/index.html检查每级目录权限
浏览器显示Nginx默认页域名未命中目标server块检查server_name、DNS以及是否存在默认站点
/api/返回HTMLAPI请求被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

相关推荐