Next.js ISR 项目部署到阿里云 FC 实战指南

以 sesefg（Next.js 16 + ISR + 多语言）为例，记录从构建到部署上线的完整流程

---

📋 概述

将 Next.js standalone 项目部署到阿里云函数计算（FC 3.0），支持 ISR、多语言路由、静态资源。

最终效果：

• 访问地址：https://sesefg-vygqnwjwgf.ap-northeast-1.fcapp.run
• 冷启动：~6s | 热启动：~0.8s

---

🚧 踩坑记录

1. Docker 内无法访问内网服务 ❌

问题： Next.js 构建时调用 getArticles() 请求 https://service.rabi.ae（本地 ngrok），Docker 构建环境无法访问。

Failed to build /[locale]/citywalk/page: /ar/citywalk after 3 attempts.
Export encountered an error on /[locale]/page: /ar, exiting the build.

解决： 改用「本地构建 + COPY 产物」方案，不在 Docker 内执行 npm run build。

2. Node.js 版本不匹配 ❌

问题： Next.js 16 要求 Node >= 20.9.0，Dockerfile 用了 node:18-alpine。

You are using Node.js 18.20.8. For Next.js, Node.js version ">=20.9.0" is required.

解决： 使用 node:20-alpine。

3. ISR 在 FC 上的限制 ⚠️

问题： ISR 缓存存在实例本地磁盘，FC 实例回收后丢失。

影响：

• 页面少（<50）→ 冷启动后首批访问慢 1-2s，之后正常 ✅
• 页面多（>100）→ 每次冷启动都要重新渲染 ⚠️
• revalidate 时间短（<60s）→ 没意义 ❌
• revalidate 时间长（>1h）→ 可接受 ✅

4. FC diskSize 参数限制 ❌

问题： diskSize: 1024 报错。

ContainerDisk must be 512 MB, or a multiple of 10240 MB (10240-204800).

解决： 使用 diskSize: 512。

---

✅ 正确部署流程

前提条件

• 本地能访问项目依赖的 API 服务（如 ngrok 暴露的后端）
• Docker + buildx（支持 amd64 交叉构建）
• 阿里云 CLI + FC 权限
• Docker Hub 账号（或 ACR）

Step 1: 确认 next.config.ts

// 必须开启 standalone 输出
const nextConfig: NextConfig = {
  output: 'standalone',
  // ... 其他配置
}

Step 2: 本地构建

cd your-nextjs-project

# 确保 .env.local 配置正确
npm run build

构建完成后确认 .next/standalone/ 目录存在：

ls .next/standalone/
# → node_modules  package.json  server.js

Step 3: 创建 .dockerignore

.git
.cursor
.vercel
node_modules

⚠️ 不要排除 .next！ standalone 和 static 都在 .next/ 下。

Step 4: 创建 Dockerfile（产物 COPY 模式）

FROM node:20-alpine
WORKDIR /app
COPY .next/standalone ./
COPY .next/static ./.next/static

ENV PORT=3000
ENV HOSTNAME=0.0.0.0
ENV NODE_ENV=production

EXPOSE 3000
CMD ["node", "server.js"]

关键点：

• 不在 Docker 内 build（避免网络/内存问题）
• 只 COPY standalone + static（镜像极小，~50MB 层）
• node:20-alpine（Next.js 16 最低要求 Node 20）

Step 5: 构建并推送镜像

docker buildx build --platform linux/amd64 \
  -t YOUR_USER/your-project:latest --push .

⚠️ 必须 --platform linux/amd64！（Mac M 系列默认 arm64）

Step 6: 创建 FC 函数

aliyun fc CreateFunction --region ap-northeast-1 \
  --body '{
    "functionName": "your-project",
    "runtime": "custom-container",
    "memorySize": 512,
    "cpu": 0.5,
    "timeout": 60,
    "diskSize": 512,
    "customContainerConfig": {
      "image": "docker.io/YOUR_USER/your-project:latest",
      "port": 3000
    },
    "environmentVariables": {
      "PORT": "3000",
      "NODE_ENV": "production"
    }
  }'

关键参数：

• cpu: 0.5（Next.js SSR 需要）
• memorySize: 512（MB）
• diskSize: 512（只允许 512 或 10240 的倍数）
• port: 3000（和 server.js 监听端口一致）

Step 7: 创建 HTTP 触发器

aliyun fc CreateTrigger --region ap-northeast-1 \
  --functionName your-project \
  --body '{"triggerName":"http","triggerType":"http","triggerConfig":"{\"authType\":\"anonymous\",\"methods\":[\"GET\",\"POST\",\"PUT\",\"DELETE\",\"OPTIONS\"]}"}'

Step 8: 验证

# 首次访问（冷启动 ~6s）
curl -s -o /dev/null -w "HTTP %{http_code} in %{time_total}s" \
  "https://your-project-xxx.ap-northeast-1.fcapp.run/zh"

# 第二次访问（热启动 ~0.8s）
curl -s -o /dev/null -w "HTTP %{http_code} in %{time_total}s" \
  "https://your-project-xxx.ap-northeast-1.fcapp.run/zh"

---

🔄 更新部署

代码更新后：

# 1. 本地重新构建
npm run build

# 2. 重新打包推送镜像
docker buildx build --platform linux/amd64 \
  -t YOUR_USER/your-project:latest --push .

# 3. 触发 FC 拉新镜像（改环境变量强制重启）
aliyun fc UpdateFunction --region ap-northeast-1 \
  --functionName your-project \
  --body "{\"customContainerConfig\":{\"image\":\"docker.io/YOUR_USER/your-project:latest\",\"port\":3000},\"environmentVariables\":{\"PORT\":\"3000\",\"NODE_ENV\":\"production\",\"V\":\"$(date +%s)\"}}"

---

💰 成本估算

配置项	值
CPU	0.5 核
内存	512MB
磁盘	512MB
按量付费	~$0.00003334/秒
月预估（低流量）	< ¥20

---

📝 两种构建模式对比

对比项	Docker 内构建	本地构建 + COPY
构建速度	慢（每次全量）	快（复用本地缓存）
网络依赖	需要 Docker 能访问 API	无（本地已能访问）
镜像大小	~200MB（含 build 依赖）	~50MB（只有 standalone）
CI/CD 适配	好（自包含）	需要构建机器能访问 API
适用场景	API 无内网依赖	API 需要内网访问（ngrok 等）

---

🔑 关键决策总结

决策点	选择	原因
构建方式	本地 build + COPY	构建时需要访问 ngrok 暴露的 API
FC 版本	3.0	支持 Docker Hub，不需要 ACR
Node 版本	20-alpine	Next.js 16 最低要求
ISR 策略	接受冷启动惩罚	页面少（<50），revalidate 1h
镜像仓库	Docker Hub	免费，无需额外开通 ACR

---

文档生成时间：2026-04-23 维护者：Schwarz