2026 Vercel Docker 完整教學
原文：Running Docker on Vercel（2026/7/13 更新） 作者：Ben Sabic @ Vercel Knowledge Base
Vercel 對 Docker 的支援在 2026 年迎來了重大更新。從 Container Registry 到 Fluid Compute 容器化部署，Vercel 現在提供了四種 Docker 整合方式：
| 面向 | 用途 |
|---|---|
| Vercel Functions（Fluid Compute） | 將容器化應用部署為自動擴展的 Serverless Function |
| Vercel Container Registry (VCR) | 儲存、推送與拉取 OCI 映像檔 |
| Vercel Sandbox | 在隔離環境中測試映像檔與執行容器化依賴服務 |
| Local Development | 在本地端使用 Docker 重現建置環境 |
本文將逐一介紹每一種方式。
1️⃣ 部署容器映像檔為 Vercel Function
這是 Docker on Vercel 的主要使用場景。只要在專案根目錄放一個 Dockerfile.vercel（或 Containerfile.vercel），Vercel 就會自動建置映像檔、儲存到 VCR，並以自動擴展的 Function 形式提供服務。
計費方式採用 Active CPU 定價——只有在你的程式碼實際運算時才收費，閒置時自動縮減至零。
何時該用 Docker 而非 Framework Auto-Detect？
- 你的應用依賴系統函式庫（如 FFmpeg、Chromium）
- 你用的框架 Vercel 還不支援自動偵測
- 你希望應用在不同環境中完全一致地執行
快速開始：一個 Dockerfile.vercel
# Dockerfile.vercel
FROM node:26-alpine
RUN npm i -g srvx
WORKDIR /app
COPY server.ts .
# srvx 預設監聽 $PORT
CMD ["srvx", "--prod"]
對應的 server.ts：
export default {
fetch(req: Request) {
return Response.json({ ip: req.headers.get("x-forwarded-for") })
}
}
靜態網站也同樣簡單——用 FROM nginx:alpine 並把檔案複製到 /usr/share/nginx/html 即可。
部署指令：
vercel deploy
或直接推送到連結的 Git 倉庫。
2️⃣ 多服務部署
你可以在一個專案中部署多個容器化應用，透過 vercel.json 定義 services 和 rewrites：
{
"services": {
"frontend": {
"root": "frontend/",
"entrypoint": "Dockerfile.vercel"
},
"backend": {
"root": "backend/",
"entrypoint": "Dockerfile.vercel"
}
},
"rewrites": [
{ "source": "/api/(.*)", "destination": { "service": "backend" } },
{ "source": "/(.*)", "destination": { "service": "frontend" } }
]
}
關鍵行為
| 行為 | 說明 |
|---|---|
| Port 解析 | 容器預設監聽 port 80，可透過環境變數 PORT 覆蓋 |
| 縮減策略 | 生產環境 5 分鐘無流量、Preview 30 秒無流量即縮減至零。縮減前發送 SIGTERM，30 秒緩衝期 |
| 可觀測性 | stdout/stderr 日誌廣播至所有進行中的請求；Vercel Observability 指標與一般 Function 相同 |
| 定價與限制 | 容器映像檔 Function 遵循與其他 Vercel Function 相同的 Active CPU 定價模式與限制 |
3️⃣ Vercel Container Registry (VCR)
VCR 是 Vercel 內建的 OCI 映像檔倉庫，主機位址為 vcr.vercel.com，支援 Docker Registry HTTP API v2，所以 docker push、docker pull、docker tag 完全相容。
完整映像檔參考格式：
vcr.vercel.com/team-slug/project-slug/my-repository:latest
認證與推送
Vercel 在建置環境中自動提供 VERCEL_OIDC_TOKEN。本地端使用需先執行：
vercel link
vercel env pull
然後登入並推送：
printf '%s' "$VERCEL_OIDC_TOKEN" | docker login vcr.vercel.com \
--username oidc \
--password-stdin
docker push vcr.vercel.com/team-slug/project-slug/my-repository:latest
Vercel 建議使用 Docker Buildx 搭配 zstd 壓縮 來優化推送效能。
4️⃣ Vercel Sandbox 與 Docker
Vercel Sandbox 提供隔離的 Linux 環境，與 Docker 有兩種整合方式：
方式 A：在 Sandbox 內執行 Docker
Sandbox 是 Firecracker microVM，擁有自己的核心與檔案系統，且有 sudo 權限，所以可以在內部啟動 Docker daemon。
import { vercelSandbox } from "@vercel/sandbox";
// 安裝 Docker
await vercelSandbox.runCommand({
sudo: true,
cmd: "dnf",
args: ["install", "-y", "docker"],
});
// 啟動 Docker daemon（背景執行）
await vercelSandbox.runCommand({
sudo: true, cmd: "dockerd", detached: true
});
// 等待 Docker 就緒
await vercelSandbox.runCommand({
sudo: true,
cmd: "sh",
args: ["-lc", "until sudo docker info >/dev/null 2>&1; do sleep 1; done"],
});
// 執行 Redis 容器
await vercelSandbox.runCommand({
sudo: true,
cmd: "docker",
args: ["run", "--rm", "-d", "--name", "redis", "redis:alpine"],
});
// 測試連線
await vercelSandbox.runCommand({
sudo: true,
cmd: "docker",
args: ["exec", "redis", "redis-cli", "PING"],
});
啟用 Persistent Sandbox 後，Docker 安裝與已拉取的映像檔會跨 session 保留。
⚠️ 注意：容器內 HTTPS 憑證問題
Sandbox 內的容器擁有自己的檔案系統與信任存儲，不會繼承 Sandbox 的 proxy CA 憑證。如果容器內需要發送 HTTPS 請求，必須手動掛載憑證：
# 掛載 Vercel proxy CA 憑證到容器內
docker run -v /etc/pki/ca-trust/source/anchors/vercel-proxy-ca.pem:/usr/local/share/ca-certificates/vercel-proxy-ca.crt ...
Debian/Ubuntu 用 update-ca-certificates，Amazon Linux/Fedora/RHEL 用 update-ca-trust。
方式 B：從自訂映像檔啟動 Sandbox
將你的映像檔推送到 VCR，然後直接從該映像檔啟動 Sandbox：
const sandbox = await vercelSandbox.create({
image: "my-repository:latest",
});
Sandbox 啟動時就會包含你映像檔中的所有套件與工具。
5️⃣ 本地端 Docker 開發
Docker 在本地開發中也扮演重要角色。要用 Docker 在本地端測試容器映像檔：
docker build -f Dockerfile.vercel -t my-app .
docker run -p 3000:3000 my-app
若要驗證 Vercel 建置流程，可先執行 vercel build，再執行 vercel deploy --prebuilt，這樣只上傳 .vercel/output 目錄而不需要傳送原始碼。
對於使用零配置框架的專案（如 Next.js），也可以透過 Dockerfile 鎖定依賴版本，確保跨機器建置環境一致。Next.js 官方提供了 Dockerfile 範例。
6️⃣ Next.js + Docker 實戰：完整範例
這邊整合官方範例與最新的 standalone 模式，展示一個生產級的 Dockerfile：
next.config.ts
const nextConfig = {
output: "standalone", // ← 啟用獨立輸出模式，大幅縮小映像檔
};
export default nextConfig;
Dockerfile（實際部署用，非 Dockerfile.vercel）
# Stage 1: Build
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Stage 2: Runner（極小化）
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
RUN mkdir .next && chown nextjs:nodejs .next
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]
建置與執行：
docker build -t my-next-app .
docker run -p 3000:3000 my-next-app
7️⃣ 使用場景決策樹
你想在 Vercel 用 Docker？
│
├─ 我要部署一個 containerized 應用
│ └─ 放 Dockerfile.vercel → vercel deploy ✅
│
├─ 我需要多個服務（frontend + backend）
│ └─ 用 vercel.json 定義 services + rewrites ✅
│
├─ 我要測試/運行容器（CI/CD, 測試依賴）
│ └─ 用 Vercel Sandbox：
│ ├─ 需要自訂環境 → 推 VCR → boot from image
│ └─ 需要跑 Redis/Postgres → sandbox 內裝 Docker
│
└─ 我要儲存/分享 container images
└─ 推送到 VCR（vcr.vercel.com/...）
資源與下一步
| 資源 | 連結 |
|---|---|
| Container Images 文件 | vercel.com/docs/container-images |
| Vercel Container Registry | vercel.com/docs/container-registry |
| Vercel Sandbox | vercel.com/docs/sandbox |
| Next.js Dockerfile 範例 | github.com/vercel/next.js/examples/with-docker |
| Vercel Services | vercel.com/docs/services |
本教學根據 2026/7/13 發布的 Vercel 官方 KB 指南編寫，內容以原文為準。