Nginx 部署单页 HTML 项目需过权限、路径解析、路由模式三关：确保 index.html 在 root 下且 Nginx 有读取权限；history 模式需配置 try_files $uri $uri/ /index.html；静态资源路径要匹配构建输出，base 配置与 Nginx root 或 alias 保持一致。
直接扔到 Nginx 的 html 目录就能访问？不一定
很多新手以为把 HTML 文件丢进 /usr/share/nginx/html/ 就完事了，结果打开是 403、404 或空白页。根本原因不是“放错位置”，而是权限、路径解析、路由模式这三关没过。
-
index.html必须在配置的root路径下，且 Nginx 有读取权限（检查ls -l和nginx -t） - 如果项目用了前端路由（比如 Vue Router 的
history模式），Nginx 默认不转发非根路径请求，需额外配置try_files - 静态资源路径写死为
/assets/xxx.js时，部署子目录（如https://example.com/myapp/）会 404，得改base配置或用相对路径
用 Nginx 部署单页 HTML 项目的最小可用配置
别抄网上一堆带 SSL、gzip、缓存的“完整配置”，先跑通再说。以下是最简但能处理 history 路由的 server 块：
server {
listen 80;
server_name example.com;
root /var/www/myapp;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}}
注意：try_files $uri $uri/ /index.html; 这一行必须存在，否则刷新子路由（如 /about）直接 404；root 路径末尾不要加斜杠，Nginx 会自己拼。
本地 build 后文件结构不对？检查 public 和 dist 的关系
Vue/React/Vite 项目执行 npm run build 后，输出目录（如 dist）里必须包含可直接被 Nginx 服务的文件：至少一个 index.html，以及它引用的 assets/ 目录。常见翻车点：
- 构建时没清空旧
dist，残留上一版的index.html引用错误 JS 路径 -
vite.config.js里base设成"/myapp/"，但 Nginxroot指向的是/var/www/myapp—— 此时应设base: "./"或用 Nginx 的alias替代root - HTML 中写了
（相对路径），但实际文件在assets/main.xxxx.js，说明构建没生效或 CDN 配置干扰了输出
上传后页面空白？优先查浏览器开发者工具的 Network 和 Console
别急着重传文件。打开 F12 → Network 标签页，刷新，看哪些请求状态码是 404（尤其是 JS/CSS）；再切到 Console，看有没有 Failed to load module script 或 Uncaught SyntaxError。典型线索：
-
GET /assets/index.abc123.js 404→ 检查dist/assets/是否真有该文件，Nginx 是否漏配静态资源缓存规则 -
MIME type ('text/html') is not executable→ Nginx 把 JS 当 HTML 返回了，通常是location ~ \.js$规则缺失或顺序错乱 -
Access to script at 'http://...' from origin 'http://...' has been blocked by CORS po→ 本地双开服务器导致跨域，不是部署问题，关掉本地 dev server 再测
licy
licy真实部署中，最耗时间的往往不是配置 Nginx，而是确认构建产物是否干净、路径是否和运行时一致。每次改完记得 nginx -t && systemctl reload nginx，别只改配置不重载。
