手把手教你将 Next.js 应用部署到腾讯云 CloudBase

你有一个 Next.js 项目，本地跑得好好的，想上线给别人用。

Vercel？国内访问时好时坏。自己买台服务器？又得折腾 Nginx、PM2、SSL 那一套，光运维就够喝一壶了。

其实还有条路——用腾讯云 CloudBase 的 HTTP 云函数。不用管服务器，不用装 Docker，把代码往上一推就能跑。SSR、API Routes 都支持，域名绑一下就是正式环境了。

这篇文章就带你从 create-next-app 开始，一步步走到线上可访问。整个过程大概 15 分钟。

开始之前，准备好这些​

• Node.js 18+（推荐 20）
• 腾讯云账号，并且开通了 CloudBase 云开发
• 记住你的 CloudBase 环境 ID（控制台首页就能看到）

如果你还没装 CloudBase CLI，后面 CI/CD 环节会用到：

npm install -g @cloudbase/cli

另外提一嘴，如果你用 Cursor、VS Code、Claude Code 这类 AI 编辑器，可以装一下 CloudBase MCP。后面部署那一步可以直接在编辑器里完成，不用切到控制台。

第一步：创建 Next.js 项目​

如果你已经有项目了，跳过这步。

npx create-next-app@latest my-cloudbase-app

选项随意，但确认一下用的是 App Router（默认就是）。

进到项目目录，跑一下确认没问题：

cd my-cloudbase-app
npm run dev

浏览器打开 http://localhost:3000，能看到 Next.js 的欢迎页就行。

第二步：改 next.config.js​

这一步是关键。CloudBase 的 HTTP 云函数需要 Next.js 输出 standalone 模式的产物，这样才能脱离 node_modules 独立运行。

打开 next.config.mjs（或 next.config.js，取决于你项目的配置），改成这样：

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

export default nextConfig

逐个说一下为什么：

• output: 'standalone' — 构建时生成独立可运行的产物，不依赖完整的 node_modules。这是部署到云函数的前提。
• images.unoptimized: true — 云函数环境没有 Sharp 做图片优化，不关的话构建会报错或运行时出问题。
• compress: true — 开启 gzip，减少传输体积。
• poweredByHeader: false — 去掉响应头里的 X-Powered-By，没必要暴露。

第三步：写 scf_bootstrap 启动文件​

HTTP 云函数需要一个叫 scf_bootstrap 的文件（注意没有扩展名），放在项目根目录。它告诉云函数怎么启动你的应用。

在项目根目录创建这个文件：

touch scf_bootstrap
chmod +x scf_bootstrap

内容如下：

#!/bin/bash

# CloudBase HTTP 云函数固定监听 9000 端口
export PORT=9000
export NODE_ENV=production

# 用 standalone 模式启动
node .next/standalone/server.js

有几个注意点：

1. 端口必须是 9000，这是 CloudBase HTTP 云函数的硬性要求，改了就跑不起来。
2. 启动命令用 node .next/standalone/server.js，因为我们配了 output: 'standalone'，构建产物在 .next/standalone/ 目录下。这种方式包体积最小，冷启动更快。CloudBase 官方文档里的示例用的是 npm start（即 next start），也能跑，但需要完整的 node_modules，体积会大不少。
3. Windows 用户特别注意：这个文件必须用 LF 换行符（Unix 格式），不能用 CRLF。用 VS Code 的话，右下角可以切换。如果换行符不对，部署后会报 exec format error，很多人栽在这里。建议在 .gitattributes 里加一行 scf_bootstrap binary，防止 Git 自动转换换行符。

第四步：构建项目​

npm run build

构建完成后，检查一下 .next/standalone/ 目录是不是存在，里面有个 server.js。

还需要把静态资源复制过去（standalone 模式不会自动包含）：

cp -r public .next/standalone/public
cp -r .next/static .next/standalone/.next/static

此时你的项目结构大概是这样：

my-cloudbase-app/
├── .next/
│   └── standalone/
│       ├── server.js         ← 入口
│       ├── public/           ← 刚复制的
│       ├── .next/static/     ← 刚复制的
│       └── ...
├── scf_bootstrap             ← 启动脚本
├── next.config.mjs
├── package.json
└── ...

第五步：部署到 CloudBase​

这里给两种方式，选你顺手的。

方式一：用 CloudBase MCP（推荐，适合 AI 编辑器用户）​

如果你的编辑器装了 CloudBase MCP，可以直接在编辑器里完成部署。MCP 会帮你创建 HTTP 云函数、上传代码、配置访问路由，一条龙。

在 AI 编辑器中，让 AI 助手执行类似这样的操作：

"帮我创建一个 HTTP 云函数叫 nextjs-app，运行时 Node.js 18.15，把当前项目部署上去"

背后 MCP 做的事情：

1. 调用 createFunction 创建 HTTP 云函数（type: "HTTP"，runtime: "Nodejs18.15"）
2. 上传项目代码（functionRootPath 指向云函数目录的父目录）
3. 调用 createFunctionHTTPAccess 配置 HTTP 访问路由

部署成功后，你会拿到一个默认访问地址：

https://{你的环境ID}.{region}.app.tcloudbase.com/nextjs-app

方式二：用 CloudBase CLI​

# 登录（第一次需要）
tcb login

# 创建 HTTP 云函数并部署
tcb fn deploy nextjs-app --path . --override

# 创建 HTTP 访问路由
tcb service create -f nextjs-app -p /nextjs-app

部署完成后，同样可以通过默认域名访问。

验证​

打开那个 URL，看到你的 Next.js 页面了吗？如果是，恭喜，最核心的部分搞定了。

如果遇到 502 或白屏，先检查这几个：

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

第六步：绑定自定义域名​

默认的 app.tcloudbase.com 域名能用，但线上环境还是得绑自己的域名。

前置条件：

• 域名已完成 ICP 备案（国内强制要求）
• 有该域名的 SSL 证书（腾讯云可以免费申请）

流程：

1. 进 CloudBase 控制台 → HTTP 访问服务
2. 点"添加自定义域名"
3. 填入域名，选择 SSL 证书
4. 创建"域名关联资源"，选择你的 HTTP 云函数 nextjs-app，触发路径设为 /
5. 到你的域名 DNS 管理后台，添加 CNAME 记录，指向控制台给你的 CNAME 值

等 DNS 生效（通常几分钟），访问你的域名就能看到应用了。

如果你用 CLI，也可以这样操作：

# 添加自定义域名（需要先拿到证书 ID）
tcb domains add your-domain.com --certid <证书ID> -e <环境ID>

# 配置路由
tcb routes set your-domain.com / --target nextjs-app --type function

第七步：环境变量​

Next.js 的环境变量分两种：

• NEXT_PUBLIC_* — 构建时注入，客户端可访问
• 其他 — 仅服务端可访问（比如数据库连接串、API Key）

服务端环境变量在 CloudBase 控制台设置：

1. 进入你的云函数 → 函数配置 → 环境变量
2. 添加键值对，比如 DATABASE_URL=mysql://...

用 MCP 也能设：

"帮我给 nextjs-app 云函数添加环境变量 DATABASE_URL，值是 mysql://..."

用 CLI：

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

有个坑要注意：通过 MCP 或 API 更新环境变量时，新值会覆盖旧值。如果函数已经有别的环境变量，先查一下再合并，否则会丢。

至于 NEXT_PUBLIC_* 变量，这个是构建时决定的，不在云函数环境变量里设。你需要在构建命令前 export，或者写在 .env.production 里。

第八步：CI/CD 自动化​

每次改完代码手动部署太累了。用 GitHub Actions 自动化一下。

在项目根目录创建 .github/workflows/deploy.yml：

name: Deploy to CloudBase

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Copy static assets
        run: |
          cp -r public .next/standalone/public
          cp -r .next/static .next/standalone/.next/static

      - name: Install CloudBase CLI
        run: npm install -g @cloudbase/cli

      - name: Login to CloudBase
        run: tcb login --apiKeyId ${{ secrets.TCB_SECRET_ID }} --apiKey ${{ secrets.TCB_SECRET_KEY }}

      - name: Deploy
        run: |
          tcb fn deploy nextjs-app --path . --override -e ${{ secrets.TCB_ENV_ID }}

你需要在 GitHub 仓库的 Settings → Secrets 里添加三个变量：

• TCB_SECRET_ID — 腾讯云 API SecretId
• TCB_SECRET_KEY — 腾讯云 API SecretKey
• TCB_ENV_ID — CloudBase 环境 ID

这样每次 push 到 main 分支，就会自动构建并部署。

踩坑备忘​

写到这里，汇总一些容易踩的坑：

scf_bootstrap 换行符问题 Windows 创建的文件默认是 CRLF 换行符，部署后会报 exec format error。解决办法：VS Code 右下角切成 LF，或者用 dos2unix scf_bootstrap 转一下。

运行时不可修改 云函数的 Node.js 运行时（比如 18.15）创建后就不能改了。如果你想升级到 20.19，只能删了重建。所以一开始想清楚用哪个版本。

图片优化必须关 不设 images.unoptimized: true 的话，Next.js 会尝试用 Sharp 做图片优化，云函数环境里没有这个二进制依赖，会直接报错。

环境变量覆盖问题 前面说了，通过 API 更新环境变量会全量覆盖。如果你的函数已经有别的变量，先查出来再合并传入。

冷启动 第一次请求或者函数长时间没被调用时，会有冷启动延迟。Next.js 项目体积较大，冷启动可能在几秒级别。如果这对你的场景比较敏感，可以考虑设置定时触发器做预热。

用 CloudBase MCP/Skills 的开发体验​

最后补一段关于 AI 辅助开发的体验。

如果你用的是支持 MCP 的 AI 编辑器（Cursor、Claude Code、VS Code + Cline 等），可以装 CloudBase MCP 来连接你的 CloudBase 环境。

装完之后，AI 助手就能直接帮你：

• 创建和部署云函数
• 查看函数日志和配置
• 管理环境变量
• 配置域名和路由

再配合 CloudBase Skills（安装命令：npx skills add tencentcloudbase/cloudbase-skills），AI 还能理解 CloudBase 的最佳实践，比如什么时候用 HTTP 云函数、什么时候用云托管，不需要你自己去翻文档。

说白了，MCP 负责"能做什么"（权限和连接），Skills 负责"该怎么做"（规范和直觉）。两个配合起来，开发体验会顺畅不少。

小结​

整个流程回顾一下：

1. create-next-app 创建项目
2. next.config.js 配置 output: 'standalone'
3. 写 scf_bootstrap，监听 9000 端口
4. npm run build + 复制静态资源
5. MCP 或 CLI 部署到 CloudBase HTTP 云函数
6. 绑定自定义域名
7. 配置环境变量
8. GitHub Actions 做 CI/CD

HTTP 云函数比起云托管（容器），胜在启动快、配置轻、成本低。对于大多数 Next.js 项目来说，这条路是够用的。

如果你跑通了，或者卡在哪一步了，评论区说一声。

参考链接：

• Next.js 部署到 HTTP 云函数（官方文档）
• CloudBase HTTP 云函数快速开始
• CloudBase 自定义域名配置
• CloudBase CLI 与 CI/CD 集成
• CloudBase MCP 接入指南
• CloudBase Skills 使用指南