★ FEATURED ARTICLE 1. 为什么我还在手动配 nginx 静态站点说出来你可能不信我经手的项目里至少有六成所谓的“部署问题”最后查下来根本不是代码的锅而是 nginx 那一亩三分地没配明白。尤其是那种“就放一个静态页面上去”的需求看着简单真动手的时候root指错目录、index没写全、权限没给对、缓存策略拍脑袋定随便哪个环节都能让你对着 403 或 404 页面发呆半小时。所以这篇东西我不打算讲什么高深的反向代理集群方案就老老实实把“用 nginx 配置一个简单的 web 网站”这件事从头到尾捋一遍把那些文档里不会写、但实际动手一定会踩的坑都摊开来说。这篇文章适合谁看如果你手头有一个静态站点——可能是打包好的前端产物、一份产品说明页、一个内部工具的操作手册或者就是你自己写的一个纯 HTML 小页面——想把它稳稳当当地挂到服务器上让人访问那这篇就是写给你的。哪怕你之前只会在宝塔面板里点按钮或者压根没碰过命令行跟着走也能落地。我会从目录规划讲到配置文件逐行拆解再讲到权限、缓存、日志这些容易被忽略但一出问题就要命的细节最后把我自己踩过的坑整理成一张速查表。全程用大白话该给命令给命令该解释为什么的地方绝不含糊。先明确一个认知nginx 配置静态站点核心就三件事——告诉它文件在哪root、告诉它默认找哪个文件index、告诉它怎么响应请求location 与各类指令。剩下的全是围绕这三件事做加固和优化。你把这三件事吃透了再花哨的需求也不过是在这个骨架上加肉。下面我就按实际动手的顺序一层层往下拆。2. 动手前的整体设计与目录规划2.1 先想清楚“文件放哪”这件事很多人上来就改nginx.conf改完发现不生效回头一查是配置文件根本没被加载或者被别的server块抢先匹配了。我的习惯是先定目录结构再动配置。目录结构定好了配置写起来就是填空题而且后期迁移、备份、加站点都清爽。我一般会在服务器上建一个统一的站点根目录比如/data/www下面按站点名分子目录。假设这次要挂的站点叫demo-site那结构就是/data/www/demo-site/ ├── index.html ├── assets/ │ ├── css/ │ ├── js/ │ └── img/ └── favicon.ico为什么不用 nginx 默认的/usr/share/nginx/html两个原因。第一那个目录是包管理器管的系统升级或者重装 nginx 时有可能被覆盖或清理你的文件放那儿心里不踏实。第二把所有站点集中在一个自定义目录下备份的时候一条tar命令打包走人迁移的时候整个目录拷过去改个root路径就完事运维成本低得多。这是我在吃过一次“升级后首页变回默认欢迎页”的亏之后养成的习惯。提示目录名别用中文、别带空格路径里也别出现特殊字符。nginx 对路径的处理虽然支持转义但你没必要给自己找麻烦。2.2 配置文件该放哪、怎么组织nginx 的配置加载逻辑是主配置nginx.conf里通过include把子配置引进来。主流发行版的包通常已经帮你建好了conf.d或sites-available/sites-enabled这类目录。我的做法是一个站点一个独立配置文件命名用站点名比如demo-site.conf放在被include的目录里。这样加站点就是加文件删站点就是删文件互不干扰排查问题时也一眼能定位。具体放哪个目录取决于你的环境。常见的两种环境类型推荐配置目录主配置里的 include 写法通用编译安装/etc/nginx/conf.d/include /etc/nginx/conf.d/*.conf;Debian 系包安装/etc/nginx/sites-enabled/include /etc/nginx/sites-enabled/*;你先去主配置里确认一下include指向哪再把站点配置丢进对应目录这是避免“改了不生效”最直接的办法。我见过太多人把配置写进conf.d结果主配置压根没 include 这个目录白忙活。2.3 方案选型为什么用独立 server 块而不是改默认站点有人图省事直接改nginx.conf里那个默认的server块。短期看是快长期看是灾难——默认块往往还承担着其他站点的兜底或者本机健康检查你把它改成自己的站点后面再加东西就打架了。正确姿势是新建一个独立的server块用server_name区分用listen指定端口。哪怕你现在只有一个站点也建议这么做因为“以后再加一个”几乎是必然发生的事到时候你就不用返工了。独立server块还有个好处日志可以单独指定。每个站点的访问日志、错误日志分开写出问题的时候直接看对应文件不用在混杂的日志里大海捞针。这个细节后面讲日志的时候还会展开。3. 核心配置逐行拆解与实操要点3.1 一个能跑起来的最小配置长什么样先给你一份我常用的最小可用配置站点名和路径按你自己的替换server { listen 80; server_name demo.example.com; root /data/www/demo-site; index index.html index.htm; location / { try_files $uri $uri/ 404; } }别看只有几行每一行都有讲究。listen 80表示监听 HTTP 默认端口server_name是域名匹配规则请求的 Host 头跟它对上才会进这个块root指定文件根目录index指定目录请求时默认找哪些文件按顺序找找到第一个就用location /匹配所有路径里面的try_files是核心逻辑——先找请求的原始文件找不到再找同名目录还找不到就返回 404。这里重点说try_files。很多人不写这行直接用默认行为结果访问一个不存在的路径时nginx 可能返回目录列表或者奇怪的 403。try_files $uri $uri/ 404的意图很明确文件存在就给文件目录存在就进目录找 index都不存在就老老实实 404。这个顺序不能乱$uri/放在$uri后面是有原因的——如果先匹配目录某些情况下会导致本该返回文件的请求被当成目录处理。这是我在一个单页应用的路由问题上折腾出来的经验虽然那个场景更复杂但原理是相通的。3.2 root 与 alias 的区别别用错了root和alias是新手最容易混淆的一对指令。简单说root是拼接alias是替换。假设root /data/www/demo-site;请求/assets/css/app.cssnginx 实际找的是/data/www/demo-site/assets/css/app.css也就是把root值加上请求路径。假设location /static/ { alias /data/www/demo-site/assets/; }请求/static/css/app.cssnginx 找的是/data/www/demo-site/assets/css/app.css也就是把匹配到的/static/部分替换成alias的值。什么时候用哪个我的经验是站点根目录用root某个特定子路径映射到别处用alias。比如你的图片实际存在另一块大盘上就可以用alias把/images/指过去。但alias有个坑——结尾的斜杠必须和location的斜杠对应上少一个斜杠就可能 404。我个人的原则是能不用alias就不用实在要用写完一定用curl -I验证一遍实际路径。3.3 权限与属主403 的头号元凶配置写对了访问还是 403九成是权限问题。nginx 的工作进程通常以nginx或www-data用户运行它得有权限读取你的文件还得有权限“穿过”每一级父目录。注意是每一级——/data、/data/www、/data/www/demo-site任何一级没有执行x权限都会导致访问失败。我常用的权限设置是这样的# 目录属主给当前操作用户组给 nginx 运行组 chown -R deploy:www-data /data/www/demo-site # 目录 755文件 644 find /data/www/demo-site -type d -exec chmod 755 {} \; find /data/www/demo-site -type f -exec chmod 644 {} \;为什么目录要 755 而不是 644因为目录需要执行权限才能进入和遍历这是文件系统的基本规则很多人只记得给文件设 644忘了目录也得有 x 位。为什么文件不用 755静态文件不需要执行权限给多了反而是安全隐患。这套组合是我反复验证下来最省心的既能正常访问又不会因为权限过宽被安全扫描挑刺。注意别图省事直接chmod -R 777。777 意味着任何用户都能改你的文件一旦站点有上传功能或者被利用后果不堪设想。这个坑我年轻时踩过后来花了半天排查一个莫名其妙的页面被篡改问题教训深刻。3.4 server_name 的匹配规则要心里有数server_name支持精确匹配、通配符、正则匹配优先级是精确 前置通配符 后置通配符 正则 默认。大多数简单站点用精确域名就够了。但有个细节值得说如果你只配了一个server块那不管请求的 Host 是什么都会落到这个块上因为它是唯一的。可一旦你加了第二个站点没匹配上的请求就会落到第一个server块或者标了default_server的那个。这就是为什么有时候“明明配了新站点访问旧域名却跳到了新页面”——顺序和默认块的问题。我的建议是显式给一个server块加default_server标记专门用来兜底返回 444 或者一个提示页避免请求乱窜。比如server { listen 80 default_server; server_name _; return 444; }return 444是 nginx 特有的直接断开连接不返回任何响应比返回 404 更干净能挡掉不少扫描器的探测。4. 完整实操流程与关键环节落地4.1 从零到访问成功的手把手步骤假设你拿到一台干净的服务器root 权限在手域名已经解析到这台机器。下面是我实际操作的完整顺序你可以照着抄。第一步装 nginx。不同系统命令不同以常见的包管理为例# Debian/Ubuntu 系 apt update apt install -y nginx # RHEL/CentOS 系 yum install -y nginx装完先别急着改配置启动一下确认服务本身没问题systemctl start nginx systemctl enable nginx systemctl status nginx看到active (running)就说明基础服务 OK。这时候用浏览器访问服务器 IP应该能看到默认欢迎页。看到欢迎页这一步很重要它证明端口通、服务活后面出问题就只可能是配置或文件的事排查范围直接缩小一半。第二步建目录、放文件。按前面说的结构把站点文件传上去。传文件的方式随你scp、rsync、或者打包上传再解压都行。我习惯用rsync因为它能增量同步改了几个文件只传变化的部分rsync -avz --delete ./dist/ userserver:/data/www/demo-site/--delete的作用是让目标目录和源目录保持一致源里删掉的文件目标里也删掉。这个参数用的时候要小心路径写错可能误删但用对了能避免旧文件残留导致的“改了没生效”问题。第三步写站点配置。在conf.d或sites-enabled下新建demo-site.conf内容就是前面那份最小配置把server_name和root换成你的实际值。第四步测试配置语法。这一步千万别跳过nginx -t输出syntax is ok和test is successful才算过。如果报错它会告诉你哪个文件哪一行有问题按提示改就行。我养成的习惯是每次改完配置先nginx -t通过了再 reload这样能把语法错误挡在生效之前避免服务直接挂掉。第五步重载配置nginx -s reload注意是reload不是restart。reload是平滑重载老连接处理完才切换用户无感知restart是硬重启会短暂中断服务。生产环境能用reload就别用restart。第六步验证。用curl看响应头和状态码curl -I http://demo.example.com/期望看到HTTP/1.1 200 OK。如果看到 403回去查权限看到 404查root路径和文件名看到 502 或连不上查服务状态和防火墙。这套对照关系我整理在后面的排查表里了。4.2 缓存策略静态站点的性能关键静态站点最大的优势就是能被缓存但缓存配不好用户看到的可能是旧版本。我的做法是按文件类型分级设置location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff2?)$ { expires 30d; add_header Cache-Control public, immutable; } location ~* \.html$ { expires 1h; add_header Cache-Control public, must-revalidate; }逻辑是这样的带哈希指纹的静态资源现代构建工具产出的 css/js 文件名里通常带一串 hash内容不会变可以放心设长缓存immutable告诉浏览器“这文件在有效期内绝对不变别来问我”。而 HTML 文件是入口内容可能随时更新缓存时间要短并且加must-revalidate让浏览器过期后必须回源确认。这里有个实操心得如果你的构建产物文件名不带 hash千万别设长缓存。我见过一个项目css 文件名固定叫app.css缓存设了 30 天结果改完样式用户死活看不到新效果最后只能让用户手动清缓存体验极差。判断标准很简单——文件名变不变决定缓存能不能设长。4.3 日志配置出问题时你的救命稻草默认日志格式信息有限我习惯给每个站点单独定义日志并且把关键字段都带上log_format demo_main $remote_addr - $remote_user [$time_local] $request $status $body_bytes_sent $http_referer $http_user_agent rt$request_time; access_log /var/log/nginx/demo-site.access.log demo_main; error_log /var/log/nginx/demo-site.error.log warn;$request_time这个字段特别有用它记录整个请求处理耗时排查“页面加载慢”时一眼就能看出是服务端慢还是网络慢。warn级别的错误日志能过滤掉大量噪音只留下真正需要关注的问题。日志轮转也别忘。nginx 包通常自带logrotate配置但如果你自定义了日志路径得确认轮转规则覆盖到了否则日志文件会无限增长把磁盘撑爆。这个坑我在一个小流量站点上踩过跑了半年没管某天磁盘告警才发现日志占了十几个 G。4.4 加一层基础安全加固简单站点也值得做几项低成本加固。首先是隐藏 nginx 版本号在http块里加server_tokens off;避免暴露具体版本被针对性利用。其次是限制请求方法静态站点通常只需要 GET 和 HEADif ($request_method !~ ^(GET|HEAD)$) { return 405; }再就是给敏感文件加访问限制比如禁止访问.git、.env这类不该暴露的文件location ~ /\.(git|env|htaccess) { deny all; return 404; }返回 404 而不是 403 是有意为之——403 等于告诉对方“这文件存在但你没权限”404 则让对方以为文件不存在信息暴露更少。这些都是小改动但组合起来能挡掉相当一部分自动化扫描。5. 常见问题排查与避坑速查5.1 状态码对照排查表下面这张表是我这些年排查静态站点问题的经验浓缩按状态码对号入座基本能覆盖八成情况现象最可能原因排查动作403 Forbidden目录或文件权限不足或父目录缺 x 位逐级检查namei -l /path/to/file404 Not Foundroot路径错、文件名大小写不符、try_files逻辑问题curl -I看实际请求路径核对磁盘文件500 Internal Server Error配置语法错、权限导致无法读取、if逻辑异常先nginx -t再看 error_log访问到默认欢迎页配置没被 include、server_name不匹配确认 include 路径检查server_name改了配置不生效没 reload、浏览器缓存、CDN 缓存nginx -s reload后强制刷新检查缓存层中文文件名 404编码问题或路径含特殊字符避免中文文件名改用英文或拼音namei -l这个命令值得单独提一句它能一次性列出路径上每一级目录的权限比手动ls -l一层层看高效得多namei -l /data/www/demo-site/index.html输出会显示每一级的属主和权限位哪一级缺 x 一目了然。这个命令是我排查 403 时的第一反应强烈建议记住。5.2 几个反直觉的坑第一个坑SELinux 导致的 403。在某些默认开启 SELinux 的系统上即使文件权限全对nginx 还是读不了因为 SELinux 的安全上下文不允许。判断方法是看 error_log 里有没有Permission denied且权限明明没问题。解决办法是给目录打上正确的上下文标签chcon -R -t httpd_sys_content_t /data/www/demo-site或者用semanage fcontext做持久化配置。这个坑我第一次遇到时查了整整一下午因为所有常规权限检查都通过了完全没想到是 SELinux 在拦。第二个坑配置文件的加载顺序。include是按文件名字母序加载的如果你的两个配置文件里有冲突的server_name先加载的会生效。命名时加个数字前缀如10-demo-site.conf能帮你控制顺序避免意外。第三个坑浏览器缓存骗了你。改完配置用浏览器验证看到的还是旧页面别急着怀疑 nginx先开无痕窗口或者curl验证。我吃过好几次“以为配置没生效其实是浏览器缓存”的亏现在一律先用curl确认服务端行为再谈浏览器表现。5.3 上线前的自检清单每次站点上线前我会过一遍这个清单花不了几分钟但能省掉大量事后救火nginx -t通过无警告curl -I首页返回 200随便挑一个静态资源css/js/图片访问返回 200 且 Content-Type 正确访问一个不存在的路径返回 404 而不是 403 或目录列表日志文件有正常写入路径正确权限检查namei -l逐级无异常缓存头符合预期curl -I看Cache-Control和Expires敏感路径.git等访问被拒这套流程走下来一个简单静态站点的配置就算彻底落地了。我个人在实际操作中的体会是nginx 配置这件事难的不是写出能跑的配置而是写出出问题时你能快速定位的配置。所以目录结构清晰、日志分开、配置独立这些“看起来多余”的规范恰恰是后期省心的关键。最后再分享一个小技巧把你验证通过的配置存一份到版本管理里下次开新站点直接复制改路径比从零写快得多也不容易漏掉那些加固项。
阅读完成 · 觉得有帮助？
