01 部署静态网站

第一个实战：用 Nginx 容器部署一个前端静态网站。以 Docusaurus 文档站为例，React / Vue 项目完全同理（只是构建命令和产物目录不同）。

1. 部署思路

静态网站的部署本质就两步：

构建：把源码编译成一堆静态文件（HTML/CSS/JS）
托管：用一个 Web 服务器（Nginx）把这些文件伺服出去

用 Docker 多阶段构建，这两步写进同一个 Dockerfile：Node 镜像负责构建，Nginx 镜像负责运行，最终镜像里只有静态文件和 Nginx，非常小。

2. 项目结构

my-site/
├── docs/                  # 站点源码（略）
├── src/
├── package.json
├── pnpm-lock.yaml
├── Dockerfile             # 本章新增
├── nginx.conf             # 本章新增
├── .dockerignore          # 本章新增
└── compose.yaml           # 本章新增

3. 编写 Dockerfile（多阶段构建）

# ---- 第一阶段：构建静态文件 ----
FROM node:20-alpine AS builder

WORKDIR /app

# 启用 pnpm（Docusaurus 项目用 npm/yarn 的话对应修改）
RUN corepack enable

# 先复制依赖清单，利用缓存
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 再复制源码并构建，产物在 /app/build
COPY . .
RUN pnpm build

# ---- 第二阶段：Nginx 托管 ----
FROM nginx:1.25-alpine

# 用自己的配置覆盖默认配置
COPY nginx.conf /etc/nginx/conf.d/default.conf

# 把构建产物拷进 Nginx 的站点目录
COPY --from=builder /app/build /usr/share/nginx/html

EXPOSE 80

React（Vite）项目产物目录是 dist，Vue CLI 是 dist，把 COPY --from=builder 那行的路径改掉即可。

4. 编写 nginx.conf

server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    # 开启 gzip 压缩，明显加快加载
    gzip on;
    gzip_types text/css application/javascript application/json image/svg+xml;
    gzip_min_length 1024;

    # 带 hash 的静态资源缓存一年
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # 单页应用路由兜底：找不到文件就回 index.html
    # （Docusaurus 是多页静态站可不加；React/Vue SPA 必加）
    location / {
        try_files $uri $uri/index.html /index.html;
    }
}

5. 编写 .dockerignore

node_modules
build
.docusaurus
.git
*.log

node_modules 必须排除：它体积巨大，而且容器里会重新安装，宿主机的版本拷进去反而会出问题。

6. 编写 compose.yaml

services:
  web:
    build: .
    image: my-site:1.0
    restart: unless-stopped
    ports:
      - "80:80"
    logging:
      options:
        max-size: "10m"
        max-file: "3"

7. 部署与更新

# 首次部署
docker compose up -d --build

# 验证
docker compose ps
curl -I http://localhost
# 返回 HTTP/1.1 200 OK 即成功

# 以后每次更新内容：拉代码 → 重新构建
git pull
docker compose up -d --build

8. 常见问题

构建太慢 / 内存不够：Node 构建吃内存，1G 内存的小服务器可能直接被 OOM 杀掉。两种解法：

本地或 CI 里构建好镜像，推到镜像仓库，服务器只 pull
本地构建出 build/ 目录传上服务器，Dockerfile 简化成只有第二阶段：

FROM nginx:1.25-alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY build /usr/share/nginx/html

访问 404：确认构建产物目录名对不对（build 还是 dist），进容器看一眼：

docker compose exec web ls /usr/share/nginx/html

改了代码但页面没变：浏览器缓存或没有 --build。强刷（Ctrl+F5）并确认部署命令带了 --build。

小结

静态站部署 = 多阶段构建（Node 构建 + Nginx 托管）
SPA 项目记得配 try_files 路由兜底
小内存服务器别在线上构建，本地构建好再上传
更新流程固定两条命令：git pull + docker compose up -d --build

下一篇部署后端应用：02-部署FastAPI应用

1. 部署思路​

2. 项目结构​

3. 编写 Dockerfile（多阶段构建）​

4. 编写 nginx.conf​

5. 编写 .dockerignore​

6. 编写 compose.yaml​

7. 部署与更新​

8. 常见问题​

小结​