NextJS 14集成Clerk Auth部署启动失败（代理连接重置）

问题描述 #

我有一个集成Clerk Auth的基础NextJS 14应用，部署后无法启动。最初通过Azure DevOps流水线部署到Azure WebApp（Linux）时启动失败，提示模糊错误；随后将应用Docker化，问题仍存在，启动失败。日志显示连接Clerk时出现以下错误：

2024-11-15T06:42:50.8240550Z Failed to proxy http://169.254.137.3:3000/clerk_1731652970815 Error: connect ECONNRESET 169.254.137.3:3000
2024-11-15T06:42:50.8242320Z     at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1605:16)
2024-11-15T06:42:50.8242359Z     at TCPConnectWrap.callbackTrampoline (node:internal/async_hooks:130:17) {
2024-11-15T06:42:50.8242390Z   errno: -104,
2024-11-15T06:42:50.8242415Z   code: 'ECONNRESET',
2024-11-15T06:42:50.8242438Z   syscall: 'connect',
2024-11-15T06:42:50.8242465Z   address: '169.254.137.3',
2024-11-15T06:42:50.8242487Z   port: 3000
2024-11-15T06:42:50.8242510Z }
2024-11-15T06:42:50.8290774Z Error: connect ECONNRESET 169.254.137.3:3000
2024-11-15T06:42:50.8291242Z     at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1605:16)
2024-11-15T06:42:50.8291281Z     at TCPConnectWrap.callbackTrampoline (node:internal/async_hooks:130:17) {
2024-11-15T06:42:50.8291308Z   errno: -104,
2024-11-15T06:42:50.8291333Z   code: 'ECONNRESET',
2024-11-15T06:42:50.8291355Z   syscall: 'connect',
2024-11-15T06:42:50.8291384Z   address: '169.254.137.3',
2024-11-15T06:42:50.8291417Z   port: 3000
2024-11-15T06:42:50.8291439Z }

使用的Dockerfile为NextJS官方模板：

FROM node:21-alpine AS base

# Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat
WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./
RUN \
  if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
  else echo "Lockfile not found." && exit 1; \
  fi


# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .


# Ensure the `generated` folder is included in the build context

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
# ENV NEXT_TELEMETRY_DISABLED=1

RUN \
  if [ -f yarn.lock ]; then yarn run build; \
  elif [ -f package-lock.json ]; then npm run build; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
  else echo "Lockfile not found." && exit 1; \
  fi

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=development
# Uncomment the following line in case you want to disable telemetry during runtime.
# ENV NEXT_TELEMETRY_DISABLED=1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Set the correct permission for prerender cache
RUN mkdir .next
RUN chown nextjs:nodejs .next

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT=3000

# server.js is created by next build from the standalone output
# https://nextjs.org/docs/pages/api-reference/next-config-js/output
ENV HOSTNAME="0.0.0.0"
CMD ["node", "server.js"]

解决方案 #

1. 修正Dockerfile中的NODE_ENV配置 #

将Dockerfile中runner阶段的ENV NODE_ENV=development改为ENV NODE_ENV=production。生产环境模式下，Clerk会使用正式的API端点，避免开发模式下的内部代理逻辑冲突，同时Next.js的性能和稳定性也会更适配生产环境。

2. 完整配置Clerk环境变量 #

确保Azure WebApp或Docker容器中已正确设置以下Clerk核心环境变量，值需与Clerk控制台完全一致：

• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
• CLERK_SECRET_KEY
• NEXT_PUBLIC_CLERK_SIGN_IN_URL
• NEXT_PUBLIC_CLERK_SIGN_UP_URL
  这些变量缺失或错误会直接导致Clerk服务连接失败。

3. 检查Next.js应用的Clerk初始化配置 #

• 确认app/(auth)/layout.tsx或Clerk初始化组件中，没有硬编码本地IP（如169.254.137.3），所有路径使用相对路径或通过环境变量配置的公共域名。
• 检查clerkMiddleware.ts中的路由保护规则，确保没有错误拦截Clerk的回调路径。

4. 验证Azure WebApp的网络与端口配置 #

• 确认Azure WebApp的容器端口映射正确，将容器的3000端口映射到WebApp的对外访问端口。
• 检查Azure网络防火墙策略，确保允许容器出站访问Clerk的API服务地址，避免流量被拦截。

5. 优化Docker启动配置 #

• 在Dockerfile的runner阶段添加健康检查，确保应用完全启动后再接受请求：

  HEALTHCHECK --interval=5s --timeout=3s \
    CMD curl -f http://localhost:3000/health || exit 1
  

• 确认.next目录的权限设置正确，避免因权限不足导致静态资源或缓存无法访问。

内容的提问来源于stack exchange，提问作者Ntwanano Rikhotso