如何将 Next.js 应用部署到腾讯云 CloudBase？HTTP 云函数方案详解

问题背景

你有一个 Next.js 项目（使用 App Router + SSR），想部署到国内环境让用户正常访问。Vercel 国内访问不够稳定，自建服务器运维成本太高。你需要一个不用管服务器、支持 SSR、国内访问稳定的部署方案。

本文的解决方案：使用腾讯云 CloudBase 的 HTTP 云函数部署 Next.js 应用，配合自定义域名、环境变量和 CI/CD 自动化。

为什么选 HTTP 云函数而不是云托管？ HTTP 云函数启动更快、配置更轻（不需要 Dockerfile），支持单实例多并发，原生兼容 Next.js 框架。

环境要求

• Node.js 18 或更高版本
• 腾讯云账号，已开通 CloudBase 云开发
• CloudBase 环境 ID（控制台首页可见）

可选工具：

• CloudBase CLI：npm install -g @cloudbase/cli
• CloudBase MCP：AI 编辑器集成，可在编辑器内完成部署

步骤一：创建或准备 Next.js 项目

如果从零开始：

npx create-next-app@latest my-cloudbase-app
cd my-cloudbase-app
npm run dev

预期结果：浏览器访问 http://localhost:3000 看到 Next.js 欢迎页。

步骤二：配置 next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  images: {
    unoptimized: true,
  },
  compress: true,
  poweredByHeader: false,
}

export default nextConfig

步骤三：创建 scf_bootstrap 启动文件

在项目根目录创建 scf_bootstrap 文件（无扩展名）：

touch scf_bootstrap
chmod +x scf_bootstrap

文件内容：

#!/bin/bash
export PORT=9000
export NODE_ENV=production
node .next/standalone/server.js

关键约束：

• 端口必须是 9000（CloudBase 硬性要求）
• 文件必须有可执行权限
• 换行符必须是 LF（Unix 格式）

常见错误：Windows 创建的文件默认 CRLF，部署后报 exec format error。解决：VS Code 右下角切换为 LF，或 dos2unix scf_bootstrap。

步骤四：构建并补全静态资源

npm run build
cp -r public .next/standalone/public
cp -r .next/static .next/standalone/.next/static

预期结果：.next/standalone/server.js 存在，且包含 public/ 和 .next/static/ 目录。

步骤五：部署到 CloudBase

方案 A：CloudBase MCP（AI 编辑器用户）

安装 CloudBase MCP 后在编辑器中让 AI 执行部署。MCP 会调用 createFunction（type: HTTP）→ 上传代码 → createFunctionHTTPAccess 配置路由。

预期结果：获得 https://{envId}.{region}.app.tcloudbase.com/nextjs-app

方案 B：CLI

tcb login
tcb fn deploy nextjs-app --path . --override
tcb service create -f nextjs-app -p /nextjs-app

部署失败排查

步骤六：绑定自定义域名

前置条件：域名已 ICP 备案 + 有效 SSL 证书。

tcb domains add your-domain.com --certid <证书ID> -e <环境ID>
tcb routes set your-domain.com / --target nextjs-app --type function

控制台：HTTP 访问服务 → 添加自定义域名 → 关联云函数 → DNS 添加 CNAME。

步骤七：配置环境变量

• NEXT_PUBLIC_*：构建时注入，放 .env.production
• 其他：云函数运行时读取，通过控制台或 CLI 设置

tcb fn config update nextjs-app --envVariables '{"DATABASE_URL":"mysql://..."}'

注意：API 更新环境变量会全量覆盖。先查再改。

步骤八：CI/CD

.github/workflows/deploy.yml：

name: Deploy to CloudBase
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - run: |
          cp -r public .next/standalone/public
          cp -r .next/static .next/standalone/.next/static
      - run: npm i -g @cloudbase/cli
      - run: tcb login --apiKeyId ${{ secrets.TCB_SECRET_ID }} --apiKey ${{ secrets.TCB_SECRET_KEY }}
      - run: tcb fn deploy nextjs-app --path . --override -e ${{ secrets.TCB_ENV_ID }}

GitHub Secrets 需配置：TCB_SECRET_ID、TCB_SECRET_KEY、TCB_ENV_ID。

补充：CloudBase MCP 和 Skills

• MCP：让 AI 编辑器操作 CloudBase 资源
• Skills：让 AI 理解最佳实践，npx skills add tencentcloudbase/cloudbase-skills
• MCP 给权限，Skills 给直觉

已知限制

• 冷启动：Next.js 包较大，首次请求可能几秒延迟，可用定时触发器预热
• 运行时不可变：Node.js 版本创建后不能改，升级需重建
• ISR：云函数无持久文件系统，ISR 可能受限（未完整验证）

参考文档：

• Next.js 部署到 HTTP 云函数
• HTTP 云函数快速开始
• 自定义域名配置
• CI/CD 集成指南
• CloudBase MCP