Nginx部署前端项目实战指南及常见错误

# 在项目根目录下执行
npm run build
# 或者
yarn build

dist/
├── css/
├── js/
├── img/
├── favicon.ico
└── index.html  <-- 入口文件

# centos
sudo yum install epel-release
sudo yum install nginx

# ubuntu
sudo apt update
sudo apt install nginx

# 启动并设置开机自启
sudo systemctl start nginx
sudo systemctl enable nginx

server {
    # 监听端口，http 默认为 80
    listen       80;
    # 服务器域名或 ip
    server_name  www.example.com;

    # 日志路径（建议配置，方便排错）
    access_log  /var/log/nginx/my-app.access.log;
    error_log   /var/log/nginx/my-app.error.log;

    # 核心配置：静态资源映射
    location / {
        # 指定静态资源文件的根目录
        # 这里对应你上传 dist 文件夹的绝对路径
        root   /usr/share/nginx/html/my-app;
        
        # 指定默认首页
        index  index.html index.htm;
    }
}

nginx -t   # 检查语法是否正确
nginx -s reload # 重载配置

server {
    listen       80;
    server_name  www.example.com;
    root   /usr/share/nginx/html/my-app;
    index  index.html;

    location / {
        # 核心指令 try_files
        # 含义：尝试按照顺序访问文件
        # 1. $uri: 找有没有对应的具体文件（比如 style.css）
        # 2. $uri/: 找有没有对应的目录
        # 3. /index.html: 如果前两个都找不到，无条件重定向到 index.html
        try_files $uri $uri/ /index.html;
    }
}

server {
    # ... 省略前面的配置 ...

    # 匹配所有以 /api/ 开头的请求
    location /api/ {
        # 后端服务地址
        # 注意：结尾是否有斜杠 '/' 区别很大，下面详细说明
        proxy_pass http://192.168.1.100:8080/;
        
        # 代理设置（标准配置，直接复制即可）
        proxy_set_header host $host;
        proxy_set_header x-real-ip $remote_addr;
        proxy_set_header x-forwarded-for $proxy_add_x_forwarded_for;
        proxy_set_header x-forwarded-proto $scheme;

        # 可选：如果后端接口响应慢，可以增加超时时间
        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
    }
}

server {
    # ... 基础配置 ...

    # --- 开启 gzip 压缩 ---
    gzip on;
    # 启用 gzip 压缩的最小文件，小于设置值的文件将不会压缩
    gzip_min_length 1k;
    # gzip 压缩级别，1-9，数字越大压缩的越好，也越占用cpu时间
    gzip_comp_level 6;
    # 进行压缩的文件类型
    gzip_types text/plain text/css text/javascript application/json application/javascript application/x-javascript application/xml;
    # 是否在http header中添加vary: accept-encoding，建议开启
    gzip_vary on;

    # --- 浏览器缓存策略 ---
    
    # 1. 针对 index.html：永远不缓存
    # 因为 index.html 引用了带 hash 的 js/css，如果它被缓存了，发版后用户将无法加载新资源
    location = /index.html {
        add_header cache-control "no-cache, no-store, must-revalidate";
        add_header pragma "no-cache";
        add_header expires "0";
        # 这里需要重新指定 root，或者利用外层的 root 配置
        try_files $uri $uri/ =404; 
    }

    # 2. 针对静态资源（js/css/图片）：设置超长缓存
    # webpack/vite 打包后的文件名都带 hash (e.g., app.a1b2c3d4.js)
    # 文件内容变了 hash 才会变，所以可以放心设置永久缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y; # 缓存一年
        add_header cache-control "public, no-transform";
        access_log off; # 静态资源访问不记录日志，减少磁盘 i/o
    }

    # 其他配置...
}

# --- 第一阶段：构建阶段 ---
# 使用 node 镜像打包
from node:18-alpine as build-stage

# 设置工作目录
workdir /app

# 先复制 package.json 安装依赖（利用 docker 缓存层）
copy package*.json ./
run npm install --registry=https://registry.npmmirror.com

# 复制源代码并构建
copy . .
run npm run build

# --- 第二阶段：生产环境 nginx ---
from nginx:stable-alpine as production-stage

# 复制第一阶段构建好的 dist 目录到 nginx 默认目录
# 注意：vite 默认打包目录是 dist，如果是 create-react-app 可能是 build
copy --from=build-stage /app/dist /usr/share/nginx/html

# 复制自定义的 nginx 配置文件（见下文 7.2）
copy nginx.conf /etc/nginx/conf.d/default.conf

# 暴露端口
expose 80

# 启动 nginx，daemon off 保证容器不退出
cmd ["nginx", "-g", "daemon off;"]

server {
    listen       80;
    server_name  localhost; # docker 内部通常用 localhost 即可

    # 开启 gzip
    gzip on;
    gzip_min_length 1k;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/javascript application/json application/javascript application/x-javascript application/xml;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
        # 解决 router history 模式 404
        try_files $uri $uri/ /index.html;
    }

    # 接口代理
    location /api/ {
        # 注意：在 docker 中，如果后端也在 docker 里，这里写后端容器的服务名
        # 如果后端在宿主机，可以使用 host.docker.internal (mac/win) 或 宿主机真实 ip
        proxy_pass http://backend-service:8080/;
        proxy_set_header host $host;
        proxy_set_header x-real-ip $remote_addr;
    }
}

# 1. 构建镜像
docker build -t my-frontend-app:v1 .

# 2. 运行容器
# -d 后台运行
# -p 80:80 将宿主机的 80 端口映射到容器的 80 端口
docker run -d -p 80:80 --name my-frontend my-frontend-app:v1

# /etc/nginx/conf.d/frontend.conf

server {
    # 1. 端口与域名
    listen       80;
    server_name  www.example.com;
    
    # 2. 根目录设置
    root   /usr/share/nginx/html/dist;
    index  index.html;

    # 3. 日志设置
    access_log  /var/log/nginx/host.access.log  main;
    error_log   /var/log/nginx/host.error.log  warn;

    # 4. gzip 压缩优化
    gzip on;
    gzip_static on; # 如果存在 .gz 文件直接使用，不现场压缩
    gzip_min_length 1k;
    gzip_buffers 4 16k;
    gzip_comp_level 6;
    gzip_types text/plain application/javascript application/x-javascript text/css application/xml text/javascript application/x-httpd-php image/jpeg image/gif image/png;
    gzip_vary on;
    gzip_disable "msie [1-6]\.";

    # 5. 主应用路由 (spa 支持)
    location / {
        # 解决单页应用 history 模式刷新 404 问题
        try_files $uri $uri/ /index.html;
        
        # 针对 index.html 设置协商缓存或不缓存
        add_header cache-control "no-cache, no-store, must-revalidate";
    }

    # 6. 静态资源长缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 30d;
        add_header cache-control "public, no-transform";
        access_log off;
    }

    # 7. 反向代理接口
    location /api/ {
        # 假设后端接口地址
        proxy_pass http://127.0.0.1:8080/api/;
        
        # 传递真实 ip
        proxy_set_header host $host;
        proxy_set_header x-real-ip $remote_addr;
        proxy_set_header x-forwarded-for $proxy_add_x_forwarded_for;
        
        # 支持 websocket (如果需要)
        proxy_http_version 1.1;
        proxy_set_header upgrade $http_upgrade;
        proxy_set_header connection "upgrade";
    }

    # 8. 错误页面处理
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}