Windows Docker+Nginx静态站点部署：挂载配置与403排查

手上常年开着一台 Windows 笔记本，Docker Desktop 就挂在托盘里，产品同学临时丢来一个压缩包：一个 index.html、一个 css 目录、一个 assets 目录，说下午要给人看一眼。这种时候我不会去装 IIS、也不会在系统里塞一个 Nginx 服务端，最省事的做法就是用 Windows Docker 起一个 Nginx 容器，把这个纯静态 Web 站点直接顶上去。整套流程熟练之后，从解压到浏览器能打开，五分钟以内。这套组合的价值不在"高级"，而在于它把"环境依赖"这件事彻底砍掉了——Nginx 版本固定、配置跟着项目走、换台机器只要装了 Docker 就能一模一样跑起来，不用再跟同事解释"你本地那个 Nginx 是 1.18 我这边是 1.24 所以配置不一样"。下面我把这几十次部署里攒下来的东西一次讲清楚，包括路径怎么挂、配置怎么分层、端口怎么算、报错怎么查，适合完全没碰过容器但会基本命令行的人，也适合已经在用 Docker 但静态站点老是 403 的人。

1. 这套方案到底解决了什么问题

1.1 从一次临时演示说起

临时演示是最考验方案轻重的场景。你要快，但不能快得留坑。我见过太多人为了省事直接在 Windows 上装一个 Nginx 的 Windows 版本，解压到 D 盘某个目录，双击 exe 启动，然后改 conf 文件、重启进程。这套流程第一次跑通没问题，问题是三个星期后你自己都忘了当时改了哪一行，更别提让另一个同事复现。Windows 版 Nginx 的进程管理也不体面，关窗口就断、任务管理器里躺着一堆残留进程、开机自启要自己写计划任务。

Docker 方案的本质是把"Nginx 的运行环境"和"你的站点文件"解耦成两件事。镜像负责提供一个干净、版本锁定的 Nginx 运行时，站点文件通过挂载的方式从宿主机送进去。改文件不用重启容器，改配置只要 reload，删掉容器不留任何系统残留。这个解耦带来的直接好处是：你可以同时跑三个不同版本的 Nginx 测兼容性，彼此不打架；也可以把整套东西打包成镜像丢给别人，对方一条命令就能起。

再说得直白一点，容器化的静态站点部署，把"我这能跑"变成了"哪都能跑"。这在跨团队协作、跨机器演示、以及后续交接给运维的场景里，价值远大于它多花的那点学习成本。

1.2 三条路线的取舍对比

在 Windows 上把一个静态站点跑起来，主流的其实有三条路。我列个表，把真实的取舍摊开说。

我选第三条，核心理由只有一句：配置和运行时的组合可以被版本化。Dockerfile 和 nginx.conf 一起进 Git 仓库，谁拉下来构建出来的东西都一样。前两条路里，Nginx 的版本是你机器上的既定事实，不是项目的一部分，这就注定会出问题。

当然也要承认代价。第一次用的人，八成会在"我明明把文件放进去了，为什么浏览器 403"这一步卡住。这个坑后面第 5 章会重点拆，根因基本都是宿主机路径和容器路径没对上，或者挂载了一个空目录覆盖掉了镜像里的默认内容。

1.3 必须提前建立的"两个路径"概念

这是整套方案里最容易出错、也最值得先讲清楚的一点。Nginx 容器内部看到的文件系统，和你 Windows 资源管理器里看到的，是两套路径。它们之间靠-v参数建立映射关系。

容器里的 Nginx 官方镜像，默认约定是这样的：静态文件放在/usr/share/nginx/html，主配置文件在/etc/nginx/nginx.conf，站点级配置在/etc/nginx/conf.d/目录下，默认有一个default.conf。日志在/var/log/nginx/。这四个位置记牢，后面所有的挂载操作都是围绕它们转。

宿主机这边，我习惯在项目根目录下建三个平级的目录：site放静态文件，conf放 Nginx 配置，logs放日志。然后启动时做三条映射。这样做的好处是，整个项目目录自成一体，拷走就能用，不会散落在 C 盘各处找不到。

注意：挂载目录时一定要用绝对路径。Windows 上的相对路径在不同 shell 里行为不一致，cmd 和 PowerShell 解析方式不同，很容易出现"Docker 在别的地方建了个空目录"的诡异现象——而空目录挂进容器，正好会覆盖掉镜像自带的欢迎页，于是你看到的就是 403。

2. Windows 侧环境准备与目录规划

2.1 Docker Desktop 的后端选择与状态自查

现在的 Docker Desktop 默认走 WSL2 后端，这个选择是对的，别去折腾旧式的 Hyper-V 后端。WSL2 后端启动快、文件性能好、和 Windows 的端口打通做得比较顺。装完之后第一件事是打开 Docker Desktop 的设置页面确认状态，然后开一个终端敲两条命令自检：

docker version docker info

docker version能同时看到 Client 和 Server 两段信息，如果只有 Client 那段、Server 报错说连不上，说明 Docker 引擎没起来，去托盘图标右键看看是不是还在启动中。docker info里重点看Server Version、Operating System、Storage Driver和Total Memory。内存这一项如果是 2GB 以下，跑 Nginx 没问题，但同时开几个容器就会紧张。

还有一个 Windows 上特有的事：防火墙。Docker Desktop 安装时会注册网络规则，一般情况下不用管。但如果你的公司电脑装了额外的安全软件，可能会拦 WSL2 的虚拟网卡，表现为容器起来了、docker ps也正常、但浏览器打不开localhost:8080。这种时候先在容器里curl一下自己，能通就说明是宿主侧的问题，再去看安全软件的拦截日志。

2.2 项目目录怎么摆最省心

我把目录结构固定成下面这样，用了两年没改过，因为它能同时兼容"直接挂载源码"和"构建成镜像"两种发布模式：

static-site/ ├── site/ │ ├── index.html │ ├── css/ │ ├── js/ │ └── assets/ ├── conf/ │ └── default.conf ├── logs/ ├── Dockerfile └── .dockerignore

site是纯粹的站点产物目录，构建工具的输出（比如前端打包后的 dist 内容）直接往这里扔，不需要在 Nginx 这边做任何额外处理。conf里只放站点级配置，主配置nginx.conf不做改动——这点很关键，很多人喜欢把整个 nginx.conf 覆盖掉，结果升级镜像版本时发现官方模板里新增的一些 include 语句丢了，调试半天。

logs目录第一次启动前可以手动建好。Windows 上如果挂载一个不存在的目录，Docker 会尝试自动创建，但创建出来的所有者可能和容器内 Nginx 的运行用户对不上，写日志时就会报权限错误。手动建目录能规避掉这一类问题。

.dockerignore不是可有可无的。它的作用是告诉docker build哪些文件不用送进构建上下文。不加的话，logs目录里的日志、.git目录、node_modules会被一股脑打包上传给 Docker 引擎，构建时间从几秒变成几十秒。这份清单我通常这么写：

logs/ .git/ node_modules/ *.log

2.3 端口规划与可达性确认

端口映射的规则是-p 宿主机端口:容器端口，容器里的 Nginx 默认监听 80，所以宿主机这边挑一个不冲突的高位端口，比如 8080。为什么不直接映射80:80？一来 Windows 上 80 端口经常被系统组件或其他服务占着，二来高位端口不需要额外权限，排查起来也方便。

启动前先确认端口没被占用。PowerShell 里这么查：

netstat -ano | findstr :8080

如果输出了内容，看最后一列的 PID，再去任务管理器对一下是哪个进程。空的说明端口可用。这个动作花十秒钟，能省掉后面"容器起来了但访问不到"的半小时。

访问地址这块要分清楚三个层次。localhost:8080或127.0.0.1:8080是本机访问，走的是 WSL2 的端口转发，一般都能通。局域网里的其他机器要访问，得用你 Windows 机器的局域网 IP，并且在防火墙里放行这个端口。第三层是容器之间互相访问，那个走的是 Docker 内部网络，用的是容器名，和宿主机端口无关——很多人在反向代理配置里写localhost:8080结果 502，根因就是没分清这一层。

3. Nginx 配置文件的分层写法

3.1 nginx.conf 与 default.conf 谁管什么

Nginx 的配置是分层级的。nginx.conf是主配置，里面管全局的东西：worker 进程数、连接数上限、日志格式、MIME 类型映射，以及最关键的include /etc/nginx/conf.d/*.conf;这一句——它把conf.d目录下所有.conf结尾的文件都包含进来。也就是说，你在default.conf里写的东西，最终是被塞进nginx.conf的http块里执行的。

理解了这层关系，就知道该改哪儿了。站点相关的、具体的路由规则、静态资源缓存策略、目录索引，全部写在default.conf里。全局的连接数、进程数，需要调就改nginx.conf。日常部署里，99% 的情况只动default.conf，主配置保持官方原样。

这里有个实操上的小技巧：如果你要挂载自己的default.conf，一定要用单文件挂载而不是目录挂载。

-v "D:/static-site/conf/default.conf:/etc/nginx/conf.d/default.conf:ro"

用单文件挂载的好处是，镜像里conf.d目录下的其他文件（如果有）不会被覆盖掉。如果用目录挂载，整个conf.d会被你的本地目录替换，一旦你少写了某个文件，行为就变了。末尾的:ro是只读，防止容器内的进程意外改写你的配置文件，这个习惯建议保持。

注意：单文件挂载在 Windows 上有个已知行为——宿主机文件被某些编辑器"另存为"式保存时，文件的 inode 会变，容器内看到的还是旧内容。表现是"我明明改了配置、也 reload 了，怎么没生效"。解决办法是重启用docker restart而不是nginx -s reload，或者干脆用目录挂载。我自己是改用目录挂载 + 只放一个文件的组合，两边的好处都占。

3.2 一份可以直接抄的 server 块

下面这份配置是纯静态站点的通用底子，我几乎每个项目都是从它起步再改：

server { listen 80; server_name localhost; charset utf-8; root /usr/share/nginx/html; index index.html index.htm; location / { try_files $uri $uri/ =404; } location ~* \.(css|js|png|jpg|jpeg|gif|svg|webp|woff2?)$ { expires 30d; add_header Cache-Control "public, max-age=2592000, immutable"; access_log off; } location = /index.html { add_header Cache-Control "no-cache, no-store, must-revalidate"; } error_page 404 /404.html; }

逐段说一下为什么这么写。charset utf-8是防中文乱码的第一道防线，虽然 HTML 里写了 meta charset 也行，但服务端响应头带上Content-Type: text/html; charset=utf-8更保险，尤其是老浏览器或者被中间层篡改的情况。

root指向容器内的默认目录，这个路径和挂载点是配套的，两边必须一致。index指定默认文档，顺序是先.html再.htm。

try_files这一行是核心。它的执行逻辑是：先找有没有和请求路径完全匹配的文件，没有就找同名目录，再没有就返回 404。这个指令决定了 Nginx 是"直接吐文件"还是"交给后端处理"。如果是单页应用（前端路由那种），要改成try_files $uri $uri/ /index.html;，让所有找不到的路径都回落到首页，由前端路由接管。这两种写法选哪个，取决于你的站点是不是单页应用，选错了表现就是刷新页面 404。

静态资源的expires 30d配合Cache-Control是缓存策略。immutable这个标记告诉浏览器"这个文件在有效期内绝不会变，别再去发请求验证了"。它成立的前提是你的文件名带内容哈希（大多数前端构建工具默认就是这样）。如果文件名是固定的，比如永远叫app.js，那用immutable就会导致更新后用户看不到新版本，这时候要改成较短的缓存时间或者干脆不缓存。

最后一条location = /index.html把首页的缓存关掉，保证用户每次拿到的都是最新的入口文件，再由入口文件去引用带哈希的资源。这个组合是静态站点缓存的通行做法。

3.3 缓存、压缩与回落的取舍逻辑

gzip要不要开？文本类资源开，图片视频不开。图片本身已经压缩过，再压一遍浪费 CPU 还可能变大。配置写在default.conf的server块里：

gzip on; gzip_comp_level 5; gzip_min_length 1k; gzip_types text/plain text/css application/javascript application/json image/svg+xml; gzip_vary on;

gzip_comp_level取值 1 到 9，压缩率和 CPU 消耗不是线性关系。1 到 5 提升明显，6 以上收益递减但 CPU 涨得快。静态站点访问量不大的时候随便设，真到高并发场景，5 是个划算的平衡点，再往上就应该考虑构建时预压缩，用gzip_static on;直接吐.gz文件，运行时零 CPU 开销。

gzip_min_length 1k是为了避免压缩那些几百字节的小文件，压缩后反而可能更大，因为 gzip 有头部开销。

gzip_vary on会加上Vary: Accept-Encoding响应头，告诉中间缓存服务器"同一个 URL 针对不同编码要分开缓存"。少了这一条，某些代理会把压缩版和未压缩版搞混，用户拿到一堆乱码。这个头很多人不写，出了问题时极难定位。

关于try_files的回落目标，还有个细节：=404和/index.html之外，其实还能回落到一个自定义错误页。但要注意error_page 404 /404.html;只有在try_files返回 404 状态码时才会触发，如果try_files直接回落到/index.html并返回 200，错误页就不会出现。这两个机制是互斥的，别指望同时生效。

4. 从零到浏览器打开的完整实操

4.1 静态文件准备与目录校验

把构建产物放进site目录，然后一定要确认入口文件在根上。我踩过最冤枉的一次坑：前端构建工具输出的目录结构多套了一层，实际是site/dist/index.html，而我挂载的是site，于是 Nginx 在根目录找不到 index 文件，返回 403。排查了半天配置，最后docker exec进去ls才发现问题。

养成一个习惯，启动前用一条命令确认：

Get-ChildItem .\site

看到index.html直接躺在第一层就对了。如果是dist目录，那就把挂载路径改成指向dist，或者把内容挪上来。我倾向后者，目录结构扁平一点，后面写 Dockerfile 的COPY也简单。

另外，Windows 的文件名大小写不敏感，但容器里的 Linux 是敏感的。本地引用写的是./Css/main.css，实际文件叫css/main.css，在 Windows 上打开一切正常，进了容器就 404。这个坑在从 Windows 开发环境往 Linux 容器迁移时特别常见，构建产物里的引用路径一定要检查一遍。前端项目里可以配个 lint 规则强制大小写一致，比事后排查省事得多。

4.2 写 Dockerfile 并构建镜像

两种发布模式，先讲构建成镜像这种。Dockerfile 短得不像话：

FROM nginx:1.25-alpine LABEL maintainer="static-site" COPY conf/default.conf /etc/nginx/conf.d/default.conf COPY site/ /usr/share/nginx/html/ EXPOSE 80 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \ CMD wget -q --spider http://localhost/ || exit 1

镜像选型上，alpine版本压缩后大约 40 多 MB，标准版 140 MB 上下。静态站点不需要额外的动态模块，alpine 完全够用，启动也快。用固定的小版本号（比如1.25-alpine）而不是latest，是为了可复现——某天官方推了个新版本，行为变了，你的构建结果就跟着变了，这种不确定性在部署环节是纯粹的负担。

HEALTHCHECK那一段值得单独说。它让 Docker 定期在容器内发一个请求，判断 Nginx 是否还能正常响应。--start-period=5s是给容器启动留的缓冲期，这段时间内的失败不计入重试次数。有了健康检查，docker ps的状态栏会显示healthy或unhealthy，编排工具也能据此做自动重启。这个小细节在单机演示时看不出价值，一旦上到多容器编排就是刚需。

构建命令：

docker build -t static-site:1.0 .

末尾那个点不能漏，它指定构建上下文是当前目录。构建过程会依次执行每一条指令，每一层都有缓存。改了site里的文件，COPY site/这一层及其之后的层会重建，前面的FROM层直接复用缓存，所以第二次构建通常几秒钟就完事。

4.3 启动容器：参数逐条拆解与并发量估算

镜像构建好了，启动：

docker run -d --name static-web -p 8080:80 --restart unless-stopped static-site:1.0

-d是后台运行。--name给容器起个固定名字，方便后续logs、exec、restart引用，不起名字的话只能记那一串随机 ID。-p 8080:80是端口映射，冒号左边宿主机、右边容器，写反了就是另一个故事。--restart unless-stopped让容器在 Docker 引擎启动时自动拉起，除非你手动停过它——这个策略比always温和，调试时手动停掉的容器不会自己复活打扰你。

如果是挂载源码的开发模式，命令换成这样：

docker run -d --name static-web-dev ^ -p 8080:80 ^ -v "D:/static-site/site:/usr/share/nginx/html:ro" ^ -v "D:/static-site/conf:/etc/nginx/conf.d:ro" ^ -v "D:/static-site/logs:/var/log/nginx" ^ nginx:1.25-alpine

在 cmd 里换行符是^，在 PowerShell 里是反引号。路径用双引号包起来，防止有空格时被截断。三个挂载点分别对应静态文件、配置、日志，静态和配置用:ro只读，日志必须可写所以不加。

关于并发能力，这里可以做个小估算。Nginx 的最大并发连接数约等于worker_processes × worker_connections。官方镜像的nginx.conf里默认是worker_processes auto;（跟随 CPU 核心数）和worker_connections 1024;。假设你给容器的宿主机是 4 核，那理论上限是 4 × 1024 = 4096 个并发连接。静态文件场景下这个数字绰绰有余，瓶颈根本不在 Nginx，而在网络带宽和磁盘 IO。所以除非你要做压测，别去动这两个参数，调大了反而增加内存和上下文切换开销。

4.4 验证、热更新与两种模式的取舍

启动后三步验证。第一步看容器状态：

docker ps

状态是Up且带上(healthy)就对了。第二步看日志：

docker logs --tail 50 static-web

正常的日志里能看到 Nginx 启动的几条信息，没有 error 级别的输出。第三步用浏览器打开http://localhost:8080。

开发模式下改文件是即时的，因为挂载是双向可见的，你改完index.html保存，浏览器刷新就能看到。改配置则要 reload：

docker exec static-web nginx -t docker exec static-web nginx -s reload

先-t检查语法，通过了再 reload。直接 reload 一个语法错误的配置，Nginx 会拒绝加载并保持旧配置运行，日志里报错，但容器不会挂——这个行为算是安全网，不过养成先测后reload的习惯更稳。

两种模式怎么选？我自己的规则是：本地开发、临时演示、变更频繁，用挂载。需要交付给别人的、要长期稳定运行的、变更走版本发布的，用构建镜像。原因是挂载模式把站点内容和运行时绑定在你本地磁盘上，别人拿到容器也没用；镜像模式把两者打包成一体，交付的是一个不可变的产物。这个区分清楚了，后面就不会出现"我把容器导出给同事，他那边打开是 403"的尴尬。

镜像模式下更新站点的流程是：改文件、docker build -t static-site:1.1 .、停掉旧容器、用新标签启动。整个过程旧容器一直在跑，新容器起来验证无误后再删旧的，零停机。

5. 常见问题与排查实录

5.1 403、404、502 的排查顺序表

这三个状态码是静态站点部署的高频访客，但根因完全不同，先分清再动手。

排查顺序上，我的固定动作是先进容器看文件：

docker exec -it static-web sh ls -la /usr/share/nginx/html

这一步能筛掉七成的问题。文件在，说明挂载对了；文件不在或者目录是空的，问题就在挂载参数上。这个顺序比翻配置快得多，因为挂载错误的概率远高于配置写错。

注意：容器里用sh而不是bash，alpine 镜像默认没有 bash。-it两个参数分别对应交互和分配终端，少一个都进不去。

5.2 Windows 上特有的三个坑

第一个是换行符。Windows 的编辑器默认存成 CRLF，Nginx 解析配置文件时，行尾的\r会被当成内容的一部分，报出来的错误是unknown directive或者unexpected "{"这种看着莫名其妙的语法错误。我第一次遇到时以为是自己少写了分号，找了半小时。判断方法很简单：

docker exec static-web cat -A /etc/nginx/conf.d/default.conf | head -20

如果行尾出现^M$，就是 CRLF。处理方式是把编辑器设成 LF 保存，或者在构建时用sed -i 's/\r$//'处理一遍。

第二个是路径格式。挂载路径在 Git Bash 里要用/d/static-site这种形式，在 PowerShell 里用D:/static-site或者D:\static-site都行，在 cmd 里推荐用%cd%拼接。混用会导致路径解析失败，Docker 默默建了个空目录挂上去，于是又是 403。有个通用写法是在 PowerShell 里用${PWD}：

-v "${PWD}/site:/usr/share/nginx/html:ro"

第三个是文件性能。WSL2 后端下，容器访问 Windows 文件系统（/mnt/d/...）的性能明显低于访问 WSL2 内部文件系统。静态站点文件小、访问量低的时候感觉不出来，但如果你挂了上千个小文件，或者做构建时的热重载，会明显卡顿。解决办法是把项目放在 WSL2 的文件系统里（\\wsl$\那个路径下），然后用 WSL 内的路径挂载。这个改动对纯静态演示意义不大，但对接前端构建工具的热更新时，差别很明显。

5.3 容器起不来与端口占用的定位

容器启动后立刻退出，docker ps里看不到，用docker ps -a能看到状态是Exited (1)。这时候唯一有用的信息在日志里：

docker logs static-web

常见的三种输出对应三种原因。nginx: [emerg] unknown directive是配置语法或换行符问题。bind() to 0.0.0.0:80 failed (98: Address already in use)是容器内的 80 被占了，这个通常发生在你自己从别的镜像里也起了 Nginx 的情况。还有一种是没有输出，直接退出码 1，那多半是CMD或ENTRYPOINT被覆盖了，检查一下docker run命令末尾有没有手贱加了个sh之类的参数。

端口冲突这边，宿主机层面查：

netstat -ano | findstr :8080

有输出就拿 PID 去任务管理器对。另一个隐蔽的情况是：你之前起过一个容器占着 8080，后来忘了。一条命令清理掉：

docker ps -a --filter "publish=8080"

找到之后docker rm -f干掉。养成给容器起名字的习惯，这时候就体现出价值了，你能一眼看出来是哪个。

5.4 中文乱码与缓存不更新的处理

中文乱码分两处。一处是响应头没带 charset，浏览器按默认编码猜。解决办法是charset utf-8;写在server块里。另一处是文件本身编码不对，编辑器存成了 GBK 之类，那就在服务端做不了什么，只能把源文件转成 UTF-8。判断方法是用file命令看编码，或者在浏览器里看响应头。

缓存不更新是另一个高频困惑。现象是改了文件、刷新页面、还是旧内容。先排除浏览器缓存，用无痕窗口或者Ctrl+F5强刷。如果无痕窗口也是旧的，那就是 Nginx 或容器层的问题。看一下响应头：

curl -I http://localhost:8080/index.html

重点看Cache-Control和ETag。如果是构建镜像模式，改完文件没重新 build，容器里当然还是旧的。如果是挂载模式，改完还是旧的，那大概率是编辑器"另存为"导致单文件挂载的 inode 失效，前面 3.1 提过这个行为，用docker restart能验证。

还有个更隐蔽的：expires 30d加上文件名不带哈希，用户浏览器缓存了旧的app.js，你更新了服务器文件但用户看不到。这个只能靠构建工具的哈希文件名解决，或者在发版时给资源路径加版本查询串。我见过最惨的一次是某个页面样式错乱，查了半天发现是用户本地缓存了一个三天前的 CSS，改配置加no-cache才解决。这也说明缓存策略要么全站统一规划，要么就别乱加。

6. 往生产靠一靠的几点优化

6.1 镜像瘦身与构建缓存

前面提过 alpine 版本 40 多 MB，标准版 140 MB。但如果你不小心把整个项目目录都COPY进去，包括node_modules和.git，镜像可能瞬间涨到几百 MB。.dockerignore是第一步。

第二步是减少层数。Dockerfile 里每一条RUN、COPY都是一层，层数多了镜像就大。常见的合并方式是：

RUN apk add --no-cache curl \ && rm -rf /var/cache/apk/*

--no-cache让包管理器不保留索引缓存，rm -rf清理残留，这两步能把 apk 带来的体积压到最小。

构建缓存的利用也有讲究。Dockerfile 里的指令顺序应该是"变化频率低的放前面，变化频率高的放后面"。FROM和安装依赖的RUN在最前，COPY site/在最后。这样你改站点文件时，前面的层全部命中缓存，构建只需要几秒。反过来把COPY写在前面，每改一个文件所有层都重建，构建时间能翻好几倍。

多阶段构建在这类场景里其实用不上，因为静态文件不需要编译。但如果是前端项目要在 CI 里构建再部署，那就可以用两阶段：第一阶段用 node 镜像跑npm run build，第二阶段用 nginx 镜像只COPY --from打包产物。这样最终镜像里不含 node 运行时，体积小一半以上。

6.2 把 HTTPS 和反向代理的位置预留出来

纯静态站点在本地跑 HTTP 完全没问题，但一旦要对外，就得考虑 HTTPS。我的做法是配置上预留位置，需要的时候填进去就行。

如果 Nginx 直接对外提供 HTTPS，server块里加listen 443 ssl;和证书路径，同时保留 80 端口做跳转：

server { listen 80; return 301 https://$host$request_uri; }

如果前面还有一层网关或负载均衡，那容器内的 Nginx 就只监听 80，把 TLS 终止放在外层。这两种架构各有取舍，前者配置集中但证书要挂进容器，后者容器干净但外层要多维护一层。我倾向后者，因为证书轮换在外层做一次就行，不用重新构建镜像。

反向代理的预留主要是路径规划。如果你以后要在同一个域名下挂多个站点或 API，可以用location前缀分流：

location /api/ { proxy_pass http://backend:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

proxy_pass末尾那个斜杠很关键。带斜杠表示把匹配到的前缀替换掉，不带则原样透传。这个差异我在项目里踩过一次，表现是后端收到的路径多了一层/api，接口全 404。这类细节建议写注释，半年后自己看到还能想起来。

6.3 我踩过的几个印象深刻的坑

说几个印象最深、当时耗了不少时间的。

第一个是日志目录权限。我挂载了logs目录想收集访问日志，结果容器起不来了。日志里报的是open() "/var/log/nginx/access.log" failed (13: Permission denied)。原因是 Windows 挂载进来的目录，映射到容器内时所有者和权限模型和 Linux 不一样，Nginx 的 worker 进程以非 root 用户运行，写不进去。解决办法有两个，一是干脆不挂日志目录，用docker logs看标准输出（官方镜像默认把 access.log 软链到 stdout）；二是在启动时用--user root或者调整挂载目录权限。我后来统一改成不挂日志，直接用docker logs加重定向到文件，省事。

第二个是default.conf挂载了但没生效。当时我挂载的路径写成了/etc/nginx/conf.d/default.conf，看着没错，但宿主机那边的文件名是defalut.conf（拼错了）。Docker 发现宿主机文件不存在，自动创建了一个空文件挂上去，然后 Nginx 加载了一个空配置，走的是默认行为。这个"自动创建空文件"的行为很坑，因为它不报错。判断方法是进容器cat一下那个文件，看内容对不对。也可以给-v加上:ro之外的检查习惯：挂载前确认文件真实存在。

第三个是路径里的空格。项目目录叫My Projects，挂载命令里没加引号，Docker 把路径截断成My，然后默默建了个叫My的目录。这个问题在 Windows 上尤其容易出，因为用户目录路径经常带空格。解决办法就是老老实实加双引号，别图省事。

第四个是容器内的时区。日志时间是 UTC，和本地时间差 8 小时，排查问题时对不上。加个环境变量-e TZ=Asia/Shanghai就能解决，前提是镜像里有对应的时区数据。alpine 镜像默认没装 tzdata，得在 Dockerfile 里RUN apk add --no-cache tzdata。这个问题不影响功能，但排查线上问题时真是折磨。

还有个小技巧分享一下：如果你想快速验证一个 Nginx 配置写得对不对，不用构建镜像、不用起容器，一条命令就够了。

docker run --rm -v "D:/static-site/conf:/etc/nginx/conf.d:ro" nginx:1.25-alpine nginx -t

--rm表示跑完就删，不留下任何东西。这个命令会输出配置语法检查结果，有错会明确指出行号。我现在的习惯是，任何配置改动都先跑这一条，通过了再去重启容器，能省下大量"启动了又崩、崩了又看日志"的来回。这个动作大概花两秒钟，但它的性价比在我用过的所有调试技巧里排得上前三。