CodeRoadMap
首页路线题库资源库文章社区
CodeRoadMap

程序员的学习成长路线图。内容免费开放,登录后可同步路线图与课时进度。

由 程序员柏风 独立维护 · 关于作者

学习

  • 路线图
  • 课程
  • 面试题
  • 文章
  • 我

更多

  • 资源
  • 社区
  • 关于作者
  • 内容说明

© 2026 CodeRoadMap

津ICP备2026012044号-1·津公网安备12011002026155号·coderoadmap@126.com
Nginx 反向代理入门/课时/安装与 nginx -t
RawBlame
课时目录12 节

Nginx 反向代理入门

  1. 01Nginx 是什么
  2. 02安装与 nginx -t
  3. 03配置文件结构
  4. 04静态资源
  5. 05反向代理基础
  6. 06双 upstream 架构
  7. 07HTTPS 与证书
  8. 08安全响应头
  9. 09缓存与性能
  10. 10负载均衡
  11. 11Nginx 与 Ingress
  12. 12综合练习

安装与 nginx -t

包管理安装、systemd、配置语法检查。

25 分钟

安装与 nginx -t

这一课你将能做到

  1. 在 Linux / WSL 上用包管理器安装 Nginx,并用 systemctl 确认 active (running)
  2. 改完配置后执行 nginx -t,根据报错行号定位问题;通过后再 reload
  3. 指出本机主配置与站点片段路径,并把 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

在 http { ... } 内找类似:

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)。
本课结论:语法检查习惯在裸机与容器里通用——坏配置不要进滚动发布。

讲清楚要点

  1. 因为配置错误会导致加载失败或行为异常,所以改完必须先 nginx -t——把失败留在检查阶段。
  2. 因为 reload 依赖 master 接受新配置,所以 -t 失败时不要强行 reload——旧配置继续服务,或状态混乱。
  3. 因为站点配置靠 include 拼进 http,所以片段必须放在被 include 的目录——只改 git 文件、不复制到机器,线上不会变。
  4. 因为 systemd 管生命周期,所以看状态用 systemctl status,看业务用 curl/日志——「进程在」≠「反代对」。
  5. 因为 Windows 开发常直连 3000/8080,所以本课环境以 Linux/WSL/云主机为准——本机不必强行装 Nginx 才能学后面概念。
  6. 因为证书与域名错误也会在 -t 或启动时暴露,所以路径写错要当配置错误修——下一课结构、SSL 课会展开。
  7. 因为官方文档以 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.log502 只会猜先看 error,再查 upstream 是否监听

自测三问

  1. 改完配置后,正确的两步操作顺序是什么?
  2. CodeRoadMap 的 test 配置示例应大致放到哪类目录才能被加载?
  3. nginx -t 通过,是否保证 /api 一定能打到 Spring Boot?为什么?

小结一句话

安装只是起点;生产铁律是 nginx -t 通过后再 reload,站点片段必须进入被 include 的目录。

官方延伸

  • Controlling nginx(信号与 reload)
  • Beginner’s Guide — Starting, Stopping, and Restarting
加载本节练习…
← 上一课Nginx 是什么下一课 →配置文件结构