🌐【教學】用 Podman + Vue + Nginx 打包你的前端專案並部署：完整步驟與常見錯誤解析

 

✨ 前言：為什麼要學會 Vue + Podman + Nginx 的部署流程？

身為軟體工程師，我們經常會開發 Vue 應用程式，但部署上線卻常是另一個世界。這篇文章是寫給「不熟 Docker、不了解容器的前端開發者」看的，我會用最簡單的例子教你如何用 Podman（Docker 替代品）+ Nginx 把 Vue 項目打包並部署，並解釋其中錯誤原因。

---

🔧 技術架構總覽

• Vue 3 前端應用 ✅

• Podman 取代 Docker 作為容器引擎 ✅

• Nginx 作為靜態檔案服務器 ✅

• 多階段 Dockerfile 打包 Vue 專案 ✅

---

🪜 步驟 1：Vue 專案目錄結構說明

你應該有如下結構（重要！否則 build 會報錯）：

front/
├── public/
│   └── index.html
├── src/
│   ├── views/
│   │   └── Home.vue
│   ├── App.vue
│   └── main.js
├── router/index.js
├── nginx.conf
├── Dockerfile
└── package.json

👉 關鍵：你的 src/views/Home.vue 必須存在，否則會導致找不到 module 的錯誤！

---

🪜 步驟 2：Dockerfile 正確寫法（多階段建置）

# Stage 1: Build Vue App
FROM node:16 AS build-stage
WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN chmod -R 777 /app
RUN npm run build

# Stage 2: Serve with Nginx
FROM nginx:stable-alpine as production-stage
WORKDIR /usr/share/nginx/html

COPY --from=build-stage /app/dist ./
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

---

🪜 步驟 3：nginx.conf 設定

server {
    listen 80;
    server_name localhost;

    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri /index.html;
    }

    error_page 404 /index.html;

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

---

🧪 步驟 4：使用 Podman 進行 Build 與執行容器

# 停止與刪除舊容器
podman stop vue-app
podman rm vue-app

# 建立新的 image（每次修改都建議重建）
podman build --no-cache -t vue-app .

# 執行容器，並映射到主機的 8080 port
podman run -d -p 8080:80 --name vue-app vue-app

---

🚨 常見錯誤解析與對應解法

錯誤訊息	解法說明
Module not found: Error: Can't resolve './views/Home.vue'	你在 App.vue 中 import 錯路徑。Vue 3 預設相對路徑，請確認是否是 ./views/Home.vue。
nginx: not found / cp: not a directory	表示你在容器內執行了錯的指令（通常這些指令應該寫在 Dockerfile 或啟動腳本中）。
npm run build 失敗	Vue 檔案路徑錯誤、缺少某個 .vue 檔案、權限不足，建議先進 Node 容器手動執行檢查。
podman run -d 成功但瀏覽器 8080 空白頁	多半是 vue-router 的路由模式需 history，你必須設 try_files $uri /index.html;。

---

✅ 最後測試：瀏覽器開啟 http://localhost:8080

如果一切正確，你應該會看到 Vue 首頁畫面。路由切換也能正確對應 Nginx 的設定。

---

📚 總結

這篇文章讓你從 0 到部署 Vue 到容器，過程中我們學會了：

• 如何編寫正確的 Vue Dockerfile（多階段）

• 如何使用 Podman 而非 Docker

• 如何避免 npm run build 路徑錯誤

• 如何使用 Nginx 服務靜態檔案 + 代理 API