安装与 nginx -t
包管理安装、systemd、配置语法检查。
安装与 nginx -t
这一课你将能做到
- 在 Linux / WSL 上用包管理器安装 Nginx,并用
systemctl 确认 active (running)
- 改完配置后执行
nginx -t,根据报错行号定位问题;通过后再 reload
- 指出本机主配置与站点片段路径,并把
deploy/nginx/test.conf.example 对照到 conf.d 的放置方式
为什么要学
装上 Nginx 很容易;用错误配置 reload 才是生产事故高发点。语法错了可能拒绝加载新配置,或在某些场景下直接起不来。
CodeRoadMap 的 prod.conf.example / test.conf.example 要落到真实机器上才生效。本课养成铁律:改 → nginx -t → 成功再 reload。
Windows 本机开发通常不装 Nginx(直接 npm run dev + Spring Boot);本课面向联调机、云主机与 WSL 预演生产入口。
先建立图像
改 conf 文件
│
▼
nginx -t ←── 语法/路径检查(必须 exit 0)
│ 失败?看 error 行号,修,再 -t
▼ 成功
systemctl reload nginx ←── 热加载,尽量不中断已有连接
│
▼
access/error 日志验证
人话:-t 像「提交前编译」;reload 像「热更新」。没编译通过就热更新,是把坏配置往线上推。
| 路径(常见) | 用途 |
|---|
/etc/nginx/nginx.conf | 主配置:events / http、全局 include |
/etc/nginx/conf.d/*.conf | 站点片段(推荐放 CodeRoadMap) |
/etc/nginx/sites-enabled/ | Debian 系「启用站点」软链目录 |
/var/log/nginx/ | access.log / error.log |
跟着做
步骤 1:安装并看版本(Ubuntu / Debian)
在有 sudo 的 Linux 或 WSL:
sudo apt update
sudo apt install -y nginx
nginx -v
应看到类似 nginx version: nginx/1.x.x。
CentOS / RHEL 系常用:sudo dnf install -y nginx(或旧版 yum)。
步骤 2:开机自启与启动
sudo systemctl enable nginx
sudo systemctl start nginx
sudo systemctl status nginx
应看到 active (running)。再测默认页:
curl -I http://127.0.0.1
期望:HTTP/1.1 200(或发行版默认欢迎页相关状态)。说明进程在听 80。
步骤 3:确认主配置如何 include 站点
# 只读查看,不要乱改全局块
sudo sed -n '1,80p' /etc/nginx/nginx.conf
include /etc/nginx/conf.d/*.conf;
# Debian 系还可能有:
# include /etc/nginx/sites-enabled/*;
在笔记写:「CodeRoadMap 站点配置应放进被 include 的目录,而不是只躺在 git 仓库里。」
步骤 4:故意写错,体验 nginx -t
sudo cp /etc/nginx/nginx.conf /tmp/nginx.conf.bak
# 在 conf.d 建一个故意坏掉的片段(示例)
echo 'server { listen 80; server_name broken; location / { proxy_pass ; } }' | sudo tee /etc/nginx/conf.d/_broken_test.conf
sudo nginx -t
应看到 syntax error 或类似失败,并带文件路径与行号。
立刻删掉坏文件:
sudo rm /etc/nginx/conf.d/_broken_test.conf
sudo nginx -t
应回到 syntax is ok / test is successful。
禁止在 -t 失败时执行 reload。
步骤 5:放入 test 配置骨架
仓库内打开 deploy/nginx/test.conf.example。复制思路:
sudo cp /path/to/repo/deploy/nginx/test.conf.example /etc/nginx/conf.d/coderoadmap-test.conf
server_name 是否匹配你的测试域名或本地 hosts
- 证书路径先可注释,仅 HTTP 实验时另建临时 server(生产必须 TLS,见 ngx-ssl)
sudo nginx -t
sudo systemctl reload nginx
# 等价:sudo nginx -s reload
步骤 6:对照 Docker 入口(建立迁移感)
容器镜像常见前台命令:nginx -g 'daemon off;'。Compose 可把 deploy/nginx 挂进容器(docker-compose)。
K8s 则更多用 Ingress Controller,而不是在每台节点 apt install(ngx-k8s)。
本课结论:语法检查习惯在裸机与容器里通用——坏配置不要进滚动发布。
讲清楚要点
- 因为配置错误会导致加载失败或行为异常,所以改完必须先
nginx -t——把失败留在检查阶段。
- 因为
reload 依赖 master 接受新配置,所以 -t 失败时不要强行 reload——旧配置继续服务,或状态混乱。
- 因为站点配置靠
include 拼进 http,所以片段必须放在被 include 的目录——只改 git 文件、不复制到机器,线上不会变。
- 因为 systemd 管生命周期,所以看状态用
systemctl status,看业务用 curl/日志——「进程在」≠「反代对」。
- 因为 Windows 开发常直连 3000/8080,所以本课环境以 Linux/WSL/云主机为准——本机不必强行装 Nginx 才能学后面概念。
- 因为证书与域名错误也会在
-t 或启动时暴露,所以路径写错要当配置错误修——下一课结构、SSL 课会展开。
- 因为官方文档以 Linux 路径与信号为准,所以本 track 命令对齐 nginx.org 习惯——
nginx -s reload 与 systemctl reload 都要认识。
你可能会懵的地方
-
reload 和 restart 差在哪?
reload:尽量平滑加载新配置;restart:停再起,连接可能中断。生产改 conf 优先 reload;改不动再排查 restart。
-
-t 通过就一定业务正确吗?
否。-t 只保证语法与部分文件可读(如证书路径存在与否因版本/场景而异)。502、路径剥错、缺头 要靠联调与日志,见反代课。
-
sites-available 和 conf.d 该用哪个?
Debian 传统用 sites-available + sites-enabled 软链;许多人生产直接 conf.d/*.conf。CodeRoadMap 示例按「一片站点 conf」理解即可,关键是 被主配置 include。
-
权限不够读证书或日志怎么办?
用 sudo。日常排错:sudo tail -n 50 /var/log/nginx/error.log。
错法对照
| 错法 | 问题 | 正解 |
|---|
-t 失败仍 reload | 新配置进不去或服务异常 | 先修到 test is successful |
只改仓库里的 example,不复制到 /etc/nginx | 线上行为不变 | 落到 conf.d(或挂载进容器) |
用 kill -9 停 Nginx | 损坏连接、未写优雅退出 | systemctl stop/reload 或 nginx -s quit |
| 在 Windows 装复杂端口抢占却不必要 | 开发体验差 | 本机直连应用;联调机再装 Nginx |
忽略 error.log | 502 只会猜 | 先看 error,再查 upstream 是否监听 |
自测三问
- 改完配置后,正确的两步操作顺序是什么?
- CodeRoadMap 的 test 配置示例应大致放到哪类目录才能被加载?
nginx -t 通过,是否保证 /api 一定能打到 Spring Boot?为什么?
小结一句话
安装只是起点;生产铁律是 nginx -t 通过后再 reload,站点片段必须进入被 include 的目录。
官方延伸