package.json中homepage配置项报错，Docker部署React至Nginx问题

我猜你大概率是在package.json里添加homepage字段后，遇到了资源加载失败、路由404或者打包报错这类问题？下面给你梳理几个常见的坑和对应的解决办法：

一、先搞懂homepage的核心作用 #

homepage是告诉React打包工具，生成的静态资源应该用什么基础路径加载。比如你部署在Nginx的/my-react-app子路径下，那homepage就得设为"/my-react-app"；如果是直接部署在Nginx根目录，要么把这个字段删掉（create-react-app默认用根路径），要么设为"/"或者"."（相对路径，适合不确定最终部署路径的场景）。

二、常见报错场景及修复方案 #

1. 静态资源加载404，控制台显示资源路径错误 #

• 如果是根路径部署：直接删掉homepage字段，或者设为"."，同时确保Nginx把React打包后的静态文件放在/usr/share/nginx/html目录下。
• 如果是子路径部署（比如Nginx的location配置为/react-app）：
  • 先把package.json里的homepage设为"/react-app"
  • 同步修改Nginx配置，确保路由和资源路径匹配：

    location /react-app {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /react-app/index.html; # 处理React单页路由的刷新问题
    }
    

2. Docker构建时打包失败 #

看你package.json里的build脚本分了build-linux和build-window，如果加了homepage后打包出错，先检查react-scripts build命令是否能正常执行——大概率是脚本里的路径移动逻辑和打包后的目录结构不匹配。另外，Dockerfile的构建步骤要规范，比如用多阶段构建：

# 第一步：用Node镜像打包React项目
FROM node:16-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build-linux # 执行你对应的Linux打包脚本

# 第二步：把打包好的静态文件复制到Nginx镜像里
FROM nginx:alpine
COPY --from=builder /app/build /usr/share/nginx/html
# 如果需要自定义Nginx配置，替换默认配置文件
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

3. React路由刷新后404 #

这是单页应用的经典问题，除了正确设置homepage，必须在Nginx配置里加try_files指令，让所有请求都指向index.html（因为React路由是前端处理的，Nginx不知道这些路由对应的文件）。根路径部署的Nginx配置示例：

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;

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

三、给你的package.json补充建议 #

根据你的部署场景，把homepage字段补全：

• 根路径部署：

  {
    "name": "react-app",
    "version": "0.1.0",
    "private": true,
    "homepage": "/", // 或者直接删掉这个字段
    "dependencies": {
      "axios": "^0.18.0",
      "bootstrap": "^4.0.0-alpha.6",
      "react": "^16.2.0",
      "react-axios": "^2.0.0",
      "react-dom": "^16.2.0",
      "react-router-dom": "^4.2.2",
      "react-scripts": "1.1.1"
    },
    "scripts": {
      "start": "react-scripts start",
      "build-window": "react-scripts build && del ../server/dist && move build ../server/dist",
      "build-linux": "react-scripts build && rm -rf ../server/dist && mv build ../server/dist"
    }
  }
  

• 子路径部署（比如/my-app）：只需要把"homepage": "/my-app"加进去就行。

如果还是报错，把具体的错误日志（比如浏览器控制台、Docker构建日志、Nginx访问日志）贴出来，就能更精准定位问题了。

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