Next.js 部署到腾讯云 CloudBase：HTTP 云函数方案实战

Next.js 项目想上线到国内，Vercel 访问不稳，自己搞服务器又不想运维------这个场景应该不少人遇到过。

今天分享一个我实际跑通的方案：用腾讯云 CloudBase 的 HTTP 云函数部署 Next.js。不用 Docker，不用 Nginx，SSR 和 API Routes 都能正常工作。整个过程从零开始大概 15 分钟。

选 HTTP 云函数而不是云托管（容器），主要是两个原因：启动快 、配置轻。云托管要写 Dockerfile、等镜像构建，HTTP 云函数直接传代码就能跑。

准备工作

Node.js 18+（推荐 20）
腾讯云 CloudBase 环境（控制台开通）
记住你的环境 ID

可选但推荐：装 CloudBase MCP，后面部署可以直接在编辑器里完成。

1. 初始化项目

perl 复制代码

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

确认 localhost:3000 能看到页面就行。已有项目跳过这步。

2. 配置 next.config.mjs

这是最关键的一步：

arduino 复制代码

/** @type {import('next').NextConfig} */
const nextConfig = {
  // 输出 standalone 产物，脱离 node_modules 独立运行
  output: 'standalone',
  // 云函数环境没有 Sharp，必须关掉图片优化
  images: {
    unoptimized: true,
  },
  // 开启 gzip
  compress: true,
  // 没必要暴露框架信息
  poweredByHeader: false,
}

export default nextConfig

这几个配置缺一不可。output: 'standalone' 是部署到云函数的前提，images.unoptimized 不加会运行时报错。

3. 写 scf_bootstrap

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

bash 复制代码

touch scf_bootstrap && chmod +x scf_bootstrap

内容：

bash 复制代码

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

9000 端口是 CloudBase HTTP 云函数的硬性要求，改了就 502。

⚠️ Windows 用户注意：这个文件必须是 LF 换行符。CRLF 会导致部署后 exec format error。VS Code 右下角可以切换。

4. 构建 + 补全静态资源

vbnet 复制代码

npm run build

# standalone 模式不含静态资源，手动复制
cp -r public .next/standalone/public
cp -r .next/static .next/standalone/.next/static

构建后确认 .next/standalone/server.js 存在。

5. 部署

方式一：CloudBase MCP（推荐）

如果你的编辑器（Cursor / Claude Code / VS Code + Cline）装了 CloudBase MCP，直接让 AI 助手执行：

"创建 HTTP 云函数 nextjs-app，运行时 Node.js 18.15，部署当前项目"

MCP 背后做的事：

createFunction（type: HTTP, runtime: Nodejs18.15）
上传代码
createFunctionHTTPAccess 配置路由

部署成功后拿到地址：https://{envId}.{region}.app.tcloudbase.com/nextjs-app

方式二：CLI

css 复制代码

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

部署后 502 排查清单

scf_bootstrap 端口是 9000？
scf_bootstrap 换行符是 LF？
.next/standalone/ 目录完整（有 server.js、public/、.next/static/）？

6. 自定义域名

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

bash 复制代码

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

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

7. 环境变量

php 复制代码

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

注意两点：

NEXT_PUBLIC_* 变量是构建时注入的，不在云函数环境变量里设
API 更新环境变量会全量覆盖，先查后改

8. CI/CD

.github/workflows/deploy.yml：

yaml 复制代码

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。

关于 MCP/Skills 的补充

CloudBase MCP 负责连接（让 AI 能操作你的云资源），CloudBase Skills 负责规范（让 AI 懂最佳实践）。

安装 Skills：npx skills add tencentcloudbase/cloudbase-skills

两个配合之后，AI 编辑器可以直接帮你创建函数、部署代码、查日志、配域名，不用在控制台和编辑器之间来回切。

踩坑汇总

问题	原因	解决
部署后 502	scf_bootstrap 端口不是 9000 或换行符错误	改端口 + `dos2unix`
图片加载报错	未关闭 Next.js 图片优化	`images.unoptimized: true`
运行时想升级	云函数运行时创建后不可改	删了重建
环境变量丢失	API 更新会全量覆盖	先查再合并
冷启动慢	Next.js 包较大	考虑定时触发器预热

参考链接：