這篇文檔詳細(xì)介紹如何將基于 Next.js 的銀企直連前置機(jī)管理系統(tǒng)(我本地的項(xiàng)目)容器化，并在本地使用 Docker 進(jìn)行部署。

1. 項(xiàng)目技術(shù)棧

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

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

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

2. 項(xiàng)目目錄結(jié)構(gòu)

項(xiàng)目的核心結(jié)構(gòu)基于 Next.js App Router：

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

3. 核心配置文件詳解

3.1 Dockerfile (多階段構(gòu)建)

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

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

dockerfile 完整配置:

# 1. 基礎(chǔ)鏡像
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. 編譯構(gòu)建階段
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# 提示：如果 build 報(bào)錯(cuò)，記得在 next.config.ts 中暫時(shí)關(guān)閉 ESLint 檢查
RUN pnpm build

# 4. 運(yùn)行階段
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
# 關(guān)鍵配置：允許從外部訪問容器內(nèi)的 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)絡(luò))

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

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: yqzl-app
    ports:
      - "3000:3000"
    env_file:
      - .env
    environment:
      # 這里重寫 MYSQL_HOST，使其指向宿主機(jī)
      # 在 Windows/Mac 的 Docker Desktop 中，host.docker.internal 指向宿主機(jī)
      - 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 名稱，允許容器內(nèi)部訪問宿主機(jī)的網(wǎng)絡(luò)服務(wù) (如本地運(yùn)行的 MySQL)。

3.3 next.config.ts (構(gòu)建配置)

針對(duì) Docker 環(huán)境，我們建議在構(gòu)建時(shí)適當(dāng)放寬檢查，以避免因細(xì)微的 Lint 錯(cuò)誤導(dǎo)致構(gòu)建失敗：

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

4. 為什么容器內(nèi)不需要 Nginx？

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

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

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

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

5. 部署步驟

1. 準(zhǔn)備環(huán)境:

   • 確保已安裝 Docker Desktop for Windows。
   • 確保本地 MySQL 服務(wù)已啟動(dòng)，且用戶權(quán)限允許遠(yuǎn)程連接 (或至少允許 Docker 網(wǎng)段連接)。

2. 配置環(huán)境:

   • 確保項(xiàng)目根目錄存在 .env 文件，且包含正確的數(shù)據(jù)庫(kù)憑證。

3. 啟動(dòng)部署: 在項(xiàng)目根目錄打開 PowerShell 或終端，運(yùn)行：

   docker-compose up -d --build
   

   • -d: 后臺(tái)運(yùn)行。
   • --build: 強(qiáng)制重新構(gòu)建鏡像 (確保代碼變更為最新)。

4. 訪問應(yīng)用: 打開瀏覽器訪問 http://localhost:3000。

5. 查看日志: 如果遇到問題，查看容器日志：

   docker-compose logs -f
   

6. 停止服務(wù):

   docker-compose down
   

到此這篇關(guān)于Docker本地部署SSR前端項(xiàng)目實(shí)戰(zhàn)指南的文章就介紹到這了,更多相關(guān)Docker本地部署SSR項(xiàng)目 內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論