Docker本地部署SSR前端項目實戰(zhàn)指南

更新時間：2026年01月15日 09:49:36 作者：新節(jié)

本文介紹了Docker本地部署SSR前端項目實戰(zhàn)指南,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友們下面隨著小編來一起學習學習吧

1. 項目技術棧

本項目采用現(xiàn)代化的 SSR (服務端渲染) 架構，主要技術棧如下：

核心框架: Next.js 15 (App Router 架構) - 提供服務端渲染、API 路由和文件系統(tǒng)路由。
前端庫: React 18 - 構建用戶界面。
UI 組件庫: Ant Design 5 - 企業(yè)級 React 組件庫。
樣式方案: Tailwind CSS 4 & Sass - 原子化 CSS 與預處理器結合。
數(shù)據(jù)庫交互: MySQL2 - Node.js 的 MySQL 驅動。
認證方案: NextAuth.js - 完整的身份驗證解決方案。
包管理工具: pnpm - 高效的包管理器。

注意：數(shù)據(jù)庫用的是我本地安裝的 MySQL，里面已有數(shù)據(jù)，省略了數(shù)據(jù)庫相關的建庫和建表。

2. 項目目錄結構

項目的核心結構基于 Next.js App Router：

yqzl/
├── app/                  # 應用主入口 (App Router)
│   ├── api/              # 后端 API 接口定義
│   ├── auth/             # 認證相關頁面
│   ├── components/       # 公共組件 (Sidebar, ConditionalLayout 等)
│   ├── dashboard/        # 儀表盤頁面
│   ├── documents/        # 文檔管理模塊
│   └── lib/              # 核心工具庫 (如 mysql 數(shù)據(jù)庫連接)
├── public/               # 靜態(tài)資源
├── types/                # TypeScript 類型定義
├── Dockerfile            # Docker 構建描述文件
├── docker-compose.yml    # 容器編排配置
├── next.config.ts        # Next.js 配置文件
└── .env                  # 環(huán)境變量 (敏感信息)

3. 核心配置文件詳解

3.1 Dockerfile (多階段構建)

為了優(yōu)化鏡像體積和構建效率，我們使用了 Docker 的多階段構建 (Multi-stage build) 功能。

Stage 1: deps: 僅復制 package.json 和 pnpm-lock.yaml 并安裝依賴。利用 Docker 緩存層，只要依賴不變，此階段會被緩存。
Stage 2: builder: 復制源碼并運行 pnpm build 進行編譯。
Stage 3: runner: 生產運行環(huán)境?；?node:20-alpine，僅復制構建產物 (.next 文件夾、public 文件夾) 和必要的 node_modules。

dockerfile 完整配置:

# 1. 基礎鏡像
FROM node:20-alpine AS base
RUN npm install -g pnpm

# 2. 依賴安裝階段
FROM base AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 3. 編譯構建階段
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# 提示：如果 build 報錯，記得在 next.config.ts 中暫時關閉 ESLint 檢查
RUN pnpm build

# 4. 運行階段
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
# 關鍵配置：允許從外部訪問容器內的 3000 端口
ENV HOSTNAME "0.0.0.0"

COPY --from=builder /app/public ./public
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json

EXPOSE 3000
CMD ["pnpm", "start"]

3.2 docker-compose.yml (編排與網(wǎng)絡)

此文件定義了如何運行應用服務，特別是解決了容器連接宿主機數(shù)據(jù)庫的問題。

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: yqzl-app
    ports:
      - "3000:3000"
    env_file:
      - .env
    environment:
      # 這里重寫 MYSQL_HOST，使其指向宿主機
      # 在 Windows/Mac 的 Docker Desktop 中，host.docker.internal 指向宿主機
      - MYSQL_HOST=host.docker.internal
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

networks:
  default:
    name: yqzl-network

host.docker.internal: 這是 Docker Desktop (Windows/Mac) 提供的特殊 DNS 名稱，允許容器內部訪問宿主機的網(wǎng)絡服務 (如本地運行的 MySQL)。

3.3 next.config.ts (構建配置)

針對 Docker 環(huán)境，我們建議在構建時適當放寬檢查，以避免因細微的 Lint 錯誤導致構建失?。?/p>

const nextConfig: NextConfig = {
  // ...
  eslint: {
    // 忽略構建時的 ESLint 錯誤，確保能夠生成鏡像
    ignoreDuringBuilds: true
  },
  typescript: {
    ignoreBuildErrors: true
  }
};

4. 為什么容器內不需要 Nginx？

在傳統(tǒng)的 SPA (Single Page Application) 部署中，前端構建出的是靜態(tài) HTML/CSS/JS 文件，因此必須依賴 Nginx 或 Apache 這樣的 Web Server 來提供文件服務。

但在 SSR (Next.js) 架構中，情況有所不同：

Node.js 自帶服務: Next.js 生產環(huán)境 (next start) 啟動的是一個全功能的 Node.js HTTP 服務器。它不僅能處理 API 請求、服務端渲染動態(tài)頁面，也能高效地托管 public 和 .next/static 中的靜態(tài)資源。
架構解耦: 根據(jù)容器化的“單一職責原則”，應用容器應該只包含應用本身。
反向代理通常在外層: 如果需要 Nginx (用于 SSL 終止、負載均衡、gzip 壓縮等)，通常建議將其部署在容器外部 (作為宿主機服務或另一個獨立的 Nginx 容器)，作為整個系統(tǒng)的網(wǎng)關 (Gateway)，而不是塞進應用容器里。

因此，直接在 Docker 中運行 pnpm start 是最簡潔、高效且符合云原生理念的做法。

5. 部署步驟

準備環(huán)境:
- 確保已安裝 Docker Desktop for Windows。
- 確保本地 MySQL 服務已啟動，且用戶權限允許遠程連接 (或至少允許 Docker 網(wǎng)段連接)。
配置環(huán)境:
- 確保項目根目錄存在 .env 文件，且包含正確的數(shù)據(jù)庫憑證。
啟動部署: 在項目根目錄打開 PowerShell 或終端，運行：
```
docker-compose up -d --build
```
- -d: 后臺運行。
- --build: 強制重新構建鏡像 (確保代碼變更為最新)。
訪問應用: 打開瀏覽器訪問 http://localhost:3000。
查看日志: 如果遇到問題，查看容器日志：
```
docker-compose logs -f
```
停止服務:
```
docker-compose down
```