企业官网建设流程全解析

1. 先从现象说起：刷新怎么就404了

1.1 两种最常见的场景：SPA路由刷新和纯静态路径

如果你访问https://localhost/index第一次正常，按 F5 刷新后直接变成 404，不用太焦虑，这个问题在本地开发里属于“每天都有几百个人遇到”的典型坑。我最初看到这个标题时，第一反应就是 Nginx 的try_files没写对，或者干脆忘了写。标题里的httpslocalhostindex虽然挤成了一串，但拆开来就是“https、localhost、index”，大概率是你的入口页面叫 index，或者项目部署在/index这个路径下，然后用 HTTPS 访问时刷新报错。

这个现象最常见的场景有两种。第一种是单页应用（SPA）用了前端路由，比如 Vue 的 history 模式、React 的 BrowserRouter，页面在浏览器里跳转时 URL 变了，但并没有真正向服务器请求新的 HTML；一旦你在这个深层链接上手动刷新，浏览器就会直接向 Nginx 请求服务器上不存在的那个路径，Nginx 没有回退规则时当然返回 404。第二种是纯静态站点也会踩到，比如你在 HTML 目录里只放了index.html，但手动访问https://localhost/index/foo，磁盘上没有foo这个文件或目录，Nginx 按请求 URI 找文件，找不到就 404。

这两种情况的本质是一样的：Nginx 默认只负责按路径找真实文件，不关心你前端路由怎么跳。把问题定位清楚，才能少走弯路。

1.2 为什么第一次能进、刷新就失败

很多人困惑的点在于：既然首页能进，说明 Nginx 配置里 root 和 index 应该没问题，那为什么刷新就挂？其实这里有一个容易被忽略的事实：首次访问https://localhost/时，Nginx 会按index指令自动找index.html，所以能正常显示。这个行为是 Nginx 自带的“目录默认首页”逻辑。

但刷新时浏览器会把当前地址栏里的完整路径原样发过去，比如https://localhost/index/foo。Nginx 收到请求后，第一步是把这个 URI 拼接到 root 目录后面，去磁盘上找对应的文件。磁盘上只有index.html，没有index/foo文件或目录，很多配置又会忽略“找不到就返回到入口页”的兜底逻辑，于是直接返回 404。你可以把 Nginx 理解成一个很听话的图书管理员：他只会按书名找实体书，你让他找一本不存在的书，他不会给你推荐别的，只会告诉你“没这本书”。

如果你还用了 HTTPS，这里会多一层干扰。有时候http://localhost下刷新正常，切到https://localhost就 404，多半是因为你写了两个 server 块，HTTP 的 server 块里加了try_files，HTTPS 的 server 块里漏了。证书本身不会导致 404，但配置不全会导致 HTTPS 下的行为跟 HTTP 不一致。

1.3 另外两个隐藏元凶：路径拼接和证书协议

除了try_files，还有两个容易被忽略的点。一个是 root 和 alias 的路径拼接问题。假设你前端项目构建后的产物放在/data/www/index目录下，你想通过https://localhost/index访问这个项目，如果你用了alias，那么请求/index/foo会映射到/data/www/index/foo，看起来没问题；但try_files里的路径是相对 root 来解析的，不是相对 alias。这个“解析基准不一致”很容易让你配出来的规则在刷新时失效，甚至让人越调越乱。

另一个是证书和浏览器缓存。自签名证书在本地 HTTPS 场景下很常见，如果你用https://localhost/index访问时浏览器提示证书不可信，或者证书只签了127.0.0.1没签localhost，刷新时浏览器可能直接拦截请求，表现成页面打不开。虽然这不是 404，但很多人会把这种“打不开”和“404”混在一起排查，白白浪费时间。

2. 核心原理拆解：Nginx是怎么找文件的

2.1 location、root 与 index 的协作关系

要彻底搞定刷新 404，必须理解 Nginx 处理一个静态文件请求的完整链条。以最简单的配置为例：

server { listen 443 ssl; server_name localhost; root /data/www; index index.html; location / { try_files $uri $uri/ /index.html; } }

用户访问https://localhost/index时，Nginx 会先看请求 URI 匹配哪个 location。这里是location /，匹配所有请求。然后它拿着 URI 里的/index去和 root 拼，得到/data/www/index。接下来，Nginx 会到磁盘上看这个路径是什么：如果它是一个文件，就直接返回；如果它是一个目录，就去这个目录里找index指令配置的默认文件，比如index.html；如果它什么都不存在，就看 location 里有没有try_files，没有的话直接 404。

很多人以为配置了root /data/www; index index.html;之后，所有路径都能自动映射到对应的 HTML 文件，其实不是。index指令只在“请求的 URI 以/结尾”或者“URI 对应的是一个目录”时才会生效。像/index这种不带尾部斜杠的路径，如果磁盘上确实有一个叫index的文件，那没问题；如果磁盘上只有index.html，但你把入口设计成/index，那 Nginx 找的是/data/www/index，而不是/data/www/index.html，自然就 404 了。

这也是为什么标题里的/index特别容易让人困惑：它到底是“一个叫 index 的文件”，还是“一个叫 index 的目录”，还是“一个叫 index 的前端路由”？配置方式完全不同。我的建议是先在服务器上执行ls -l /data/www看一眼实际目录结构，搞清楚入口文件到底叫什么，再写配置，别凭感觉猜。

2.2 try_files 的工作机制与 fallback

try_files是解决刷新 404 的核心指令，它的语法是：

try_files file1 [file2 ...] fallback;

它按顺序检查每个参数对应的文件在磁盘上是否存在。如果存在，就对该文件做内部重定向并返回；如果不存在，就继续查下一个；如果全部不存在，就用最后一个参数作为兜底。最后一个参数可以是一个 URI，也可以是命名 location，写法非常灵活。

最常见的 SPA 配置是：

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

$uri是当前请求的 URI，比如/index/foo。第一个检查项是请求路径本身对应的文件，第二个是请求路径作为目录时找默认首页，第三个是兜底：所有找不到的都交给/index.html。这里的关键是最后一个参数必须带上根路径/。如果你写成index.html，Nginx 会把它当作相对路径去拼接，结果可能指向错误位置。我之前就见过有人把 fallback 写成try_files $uri $uri/ index.html;，结果请求/index/foo时内部跳转到了/index/foo/index.html，照样 404。

如果你想用命名 location 做更精细的控制，也可以这样：

location / { try_files $uri $uri/ @fallback; } location @fallback { rewrite ^ /index.html last; }

命名 location 的好处是可以额外加一些头信息或者重写规则，但对于绝大多数本地开发和静态部署场景，直接写/index.html就已经够了。

2.3 为什么刷新会请求到磁盘文件

Nginx 本身是一个高性能静态服务器，它默认不“认识”你前端路由的规则。对于它来说，https://localhost/index/login就是一个静态文件请求，它只关心磁盘上有没有login这个文件或目录。如果你的前端项目用了 history 路由，浏览器地址栏里的/index/login只是前端框架模拟出来的路径，真实文件并不存在。首次通过点击链接跳转时，前端框架拦截了浏览器默认行为，不发出真实请求；一旦刷新，浏览器可不会再配合你，它会老老实实把 URL 发给服务器。

这种情况其实不只在本地开发会遇到，生产环境部署 SPA 时同样会踩。区别只是生产环境一般有团队沉淀好的 Nginx 模板，而本地开发经常是从零开始写配置，漏掉try_files的概率就高得多。用 curl 模拟一下就能看到全过程：

curl -k -i https://localhost/index/login

如果返回的是404 Not Found，而且响应体是 Nginx 默认的<html>...Not Found</html>，基本可以断定是没有兜底规则；如果返回的是 200 且内容里有你前端项目里index.html的标记，说明try_files已经生效了。

2.4 用生活化的类比理解整个链路

我用一个图书馆管理员的例子帮你建立直观印象。想象你去图书馆，第一次你说“我要去大厅”，管理员把你领到了大厅，大厅里摆着一本《总目录》，一切正常。然后你在里面逛了一圈，记下了一个位置叫“三楼靠窗A区书柜”，下次你直接告诉管理员“带我去这个位置”，管理员去查楼层目录，发现这个位置根本没有登记，他就会说“没这个地方”，也就是 404。

try_files相当于你提前告诉管理员：“如果以后有读者问一个我这边没有登记的位置，直接把他带回大厅，让他自己用《总目录》去找。”也就是说，所有不存在的路径，都回到index.html，由前端路由自己去解析 URL 并渲染正确页面。这样既保持了地址栏里 URL 的“假象”，又能让刷新之后页面依然正常显示。

3. 实操修复：一套可以“抄作业”的配置

3.1 最简 SPA 配置模板（含 HTTPS）

先给出一套我本地经常用的最小配置，适合入口文件就是index.html、项目直接部署在根目录的场景：

server { listen 443 ssl; server_name localhost; ssl_certificate /usr/local/etc/nginx/ssl/localhost.crt; ssl_certificate_key /usr/local/etc/nginx/ssl/localhost.key; root /data/www; index index.html; location / { try_files $uri $uri/ /index.html; } }

解释几个关键点：

• listen 443 ssl;表示监听 HTTPS 端口并启用 SSL。
• ssl_certificate和ssl_certificate_key指向本地自签名证书。
• root /data/www;是站点根目录，你的构建产物要放在这个目录下面。
• location / { try_files $uri $uri/ /index.html; }是所有静态路径的兜底规则。

如果你访问的入口地址是https://localhost/index，而不是https://localhost/，那么你要保证请求/index时也能落到这个 location。上面这套配置中，location /会匹配所有请求，所以/index也会走到try_files，最终回退到/index.html。也就是说，只要磁盘上有/data/www/index.html，访问https://localhost/index就会返回它。

这里还有一个容易踩的细节：如果你希望访问https://localhost/和https://localhost/index显示同一个页面，但后者在刷新https://localhost/index/foo时正常，那么try_files的 fallback 一定要写/index.html，不要写/index/index.html，除非你的入口文件真的在index子目录里。这个要看实际目录结构，别照搬模板。

3.2 带子路径的配置：项目在 /index 下

如果你的前端项目不是部署在根目录，而是希望访问https://localhost/index时进入一个叫 index 的项目，并且所有前端路由都在/index/...下，那配置要稍微调整。假设你的构建产物放在/data/www/index目录下，最稳妥的方案是用 root 而不是 alias：

server { listen 443 ssl; server_name localhost; ssl_certificate /usr/local/etc/nginx/ssl/localhost.crt; ssl_certificate_key /usr/local/etc/nginx/ssl/localhost.key; root /data/www; index index.html; location /index { try_files $uri $uri/ /index/index.html; } }

这里root /data/www;意味着请求/index会映射到/data/www/index，请求/index/foo会映射到/data/www/index/foo。由于磁盘上只有/data/www/index/index.html，没有/data/www/index/foo，所以try_files会把请求回退到/index/index.html。注意 fallback 里的路径也是基于 root 的，因此写/index/index.html才对应磁盘上的/data/www/index/index.html。

很多人在这个场景下会尝试用一个location /index加alias /data/www/index;的写法，但try_files和 alias 组合时有一个非常隐蔽的坑：Nginx 在解析try_files内部路径时，使用的是 root 上下文，而不是 alias 上下文。假设你写了：

location /index { alias /data/www/index; try_files $uri $uri/ /index/index.html; }

这里$uri是/index/foo，在 alias 下它确实映射到/data/www/index/foo，看起来没问题；但 fallback 的/index/index.html是按 root 解析的，如果 root 不是/data/www，就会解析到一个奇怪的位置，导致 404。这个坑我踩过两次，排查的时候看日志，发现 Nginx 去/data/www/index/index.html找文件，但明明文件就在那里，后来才意识到是 root 和 alias 的解析基准不一致。建议子路径场景一律用 root + 物理目录结构，简单直接，不容易出错。

3.3 生成本地 HTTPS 证书并在 Nginx 中启用

标题里带了 https，所以本地证书这块还是要讲一下。如果只是为了本地开发调试，可以用 openssl 命令生成自签名证书。我一般会同时把localhost和127.0.0.1都加进 SAN 扩展里，不然浏览器可能会提示证书名称不匹配。

生成证书的命令如下：

openssl req -x509 -newkey rsa:2048 \ -nodes \ -keyout localhost.key \ -out localhost.crt \ -days 365 \ -subj "/CN=localhost" \ -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

参数说明：

• -x509表示直接生成自签名证书，而不是证书签名请求。
• -newkey rsa:2048生成一个 2048 位的 RSA 私钥。
• -nodes表示私钥不加密，这样 Nginx 启动时不需要输入密码。
• -keyout和-out分别是私钥和证书的输出路径。
• -subj "/CN=localhost"设置证书的通用名称。
• -addext是 OpenSSL 1.1.1 以上版本支持的扩展字段，把localhost和127.0.0.1都写进 SAN。

生成后把两个文件放到 Nginx 能读取的目录，比如/usr/local/etc/nginx/ssl/，然后在 server 块里引用。配置改完后记得执行nginx -t检查语法，再nginx -s reload重载。

有一点要特别说明：自签名证书导致的浏览器“不是安全连接”提示，和刷新 404 是两回事。如果你用curl -k https://localhost/index能拿到 200，但浏览器里提示证书错误，那是证书信任问题，不是 Nginx 路径问题。很多人在这两者之间反复横跳，浪费时间。你可以在浏览器里点“高级”继续访问，或者把证书导入系统钥匙串后重新打开。

3.4 修改后如何验证配置和重启

配置写完不要急着刷新浏览器，先在终端里验证。第一步是检查配置语法：

nginx -t

如果输出类似syntax is ok和test is successful，说明配置语法没问题。然后重载：

nginx -s reload

重载后再用 curl 模拟实际请求：

curl -k -i https://localhost/index curl -k -i https://localhost/index/foo

第一条命令用来确认入口页面能被正常访问，第二条命令用来验证深层路由是否也能返回入口页面的内容，而不再是 404。-k参数是告诉 curl 跳过证书校验，因为本地自签名证书本来就不受信任。如果第二条返回了 HTTP/200 且响应体里包含你的前端项目内容，就可以放心去浏览器里按 F5 了。

如果 curl 仍然返回 404，再去翻 Nginx 的错误日志。默认日志路径一般是在/usr/local/var/log/nginx/error.log或者/var/log/nginx/error.log，具体看你编译安装时配置的路径。日志里如果出现/index/foo对应的open() failed ... No such file or directory，那就说明 Nginx 确实在尝试找磁盘文件，但没找到，属于典型的try_files缺失或 fallback 配置错误。

4. 常见问题排查实录：404到底怎么“查案”

4.1 先分清楚：是 Nginx 返回的 404 还是应用返回的 404

排查任何 404 问题，第一步永远是分清楚这个 404 是谁产生的。Nginx 返回的 404 通常是它自带的错误页，响应体很短，大概长这样：

<html> <head><title>404 Not Found</title></head> <body> <center><h1>404 Not Found</h1></center> <hr><center>nginx/1.25.3</center> </body> </html>

而应用自己返回的 404 会包含你前端项目里的内容，比如 Vue Router 或 React Router 渲染的空白页、错误提示等。区分方法很简单：用 curl 看响应体的 HTML 里有没有你的项目特征。如果返回的是 Nginx 默认错误页，说明请求压根没有进入前端应用，问题出在 Nginx 的路由兜底；如果返回的是你的应用页面但状态码是 404，那通常是前端路由配置的问题，比如 history 模式下的服务端 fallback 没配好，或者路由路径写错了。

我在本地排查时习惯先看 HTTP 状态码加响应体前 200 个字符。你可以用：

curl -k -s https://localhost/index/foo | head -c 200

如果看到<center>nginx</center>基本就是 Nginx 层的问题，直接往下查 location 和 try_files；如果看到你自己的<div id="app">之类的结构，那就去检查前端路由配置。

4.2 curl 和日志的配合使用

curl 是排查这类问题最好用的工具，因为它不受浏览器缓存、证书弹窗、前端跳转逻辑的影响，能看到服务器真正返回了什么。我常用的几个命令：

# 查看响应头，重点看状态码和 Server 字段 curl -k -I https://localhost/index/foo # 查看完整响应头与响应体 curl -k -i https://localhost/index/foo # 指定 Host 请求，绕过 DNS 和 server_name 匹配干扰 curl -k -H "Host: localhost" -i https://127.0.0.1/index/foo

第三条命令在排查多个 server 块的场景特别有用。如果你本机除了 Nginx 还有别的服务占用了 443 端口，或者 Nginx 里配置了多个 server 块，直接访问https://localhost可能会落到默认 server，而不是你预期的那一个。用curl -k -H "Host: localhost" https://127.0.0.1/index/foo可以绕开 localhost 的 DNS 解析，直接请求 Nginx 监听的 IP，再通过 Host 头控制 server_name 匹配，这样就能确认是不是server_name localhost这个 server 块在生效。

日志方面，重点看两个文件。access log 记录所有请求的状态码，error log 会记录 Nginx 尝试打开文件失败的详细路径。比如 error log 里写着：

[error] 12345#0: *123 open() "/data/www/index/index/foo" failed (2: No such file or directory)

这个路径非常关键，能看到 Nginx 实际是去哪个目录找文件了。如果你以为它在/data/www目录下找/index/foo，但日志显示它去/data/www/index/index/foo找，那就说明 root 或 fallback 里的路径写错了，多了或者少了一层index，根据实际目录结构修正即可。

4.3 权限、软链接、证书过期等非典型原因

有些刷新 404 问题不是路由兜底没写，而是文件和权限层面的问题。我遇到过几次这样的情况：Nginx 配置完全没问题，try_files也写了，但 Linux 上目录的权限不对，导致 Nginx worker 进程无法读取入口文件。常见现象是index.html能访问，但深层目录下的静态资源 403 或 404。这种情况不要在 Nginx 配置里反复折腾，先看目录权限：

ls -l /data/www/index/index.html ps aux | grep nginx

第一行看文件权限，第二行看 Nginx 的 worker 进程以什么用户运行。如果文件权限是600或者目录没有x权限，而 worker 进程是www-data用户，那就需要调整权限。我用的是：

chmod -R 755 /data/www

当然具体权限策略要看你的目录结构，但本地开发环境直接放开读权限是最省心的方案。

另外还有两个非典型原因：软链接和证书过期。如果你的/data/www是指向其他位置的软链接，Nginx 在读取时可能会因为路径解析不一致而出现问题。排查时可以用realpath或readlink -f查看实际路径，确认配置里的 root 没有指错。证书过期则不会表现为 404，它会在浏览器里直接拦截请求，显示NET::ERR_CERT_DATE_INVALID之类的错误。这种问题要重新生成证书，而不是在 Nginx 路径规则里找原因。

4.4 一套排查速查表

我把常见现象、可能原因、检查手段和解决方向整理成一个表，你在排查时可以直接对着看。

这个表基本覆盖了我在本地和服务器环境里遇到过的绝大多数刷新 404 场景。你可以把它保存下来，下次遇到问题先对号入座，比自己一行行翻配置高效得多。

最后再分享一个小经验：改完 Nginx 配置后，别急着在浏览器里验证。浏览器有缓存，可能在你按下 F5 之前就已经缓存了旧的 404 响应。我习惯先用 curl 确认服务器层面已经返回 200 了，再回浏览器里按 Ctrl+Shift+R 强制刷新，这样能避免“明明配置改了，浏览器还是 404”的假象。还有，排查时要养成看 error.log 的习惯，那条open() failed的日志会直接告诉你 Nginx 到底在找哪个文件，很多所谓“诡异”的 404，其实都只是路径拼接里多了一层或少了一层目录。