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


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

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

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

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

## 开始之前，准备好这些


- **Node.js 18+**（推荐 20）

- **腾讯云账号**，并且开通了 [CloudBase 云开发](https://console.cloud.tencent.com/tcb)

- 记住你的 **CloudBase 环境 ID**（控制台首页就能看到）


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

```
npm install -g @cloudbase/cli
```
另外提一嘴，如果你用 Cursor、VS Code、Claude Code 这类 AI 编辑器，可以装一下 [CloudBase MCP](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started)。后面部署那一步可以直接在编辑器里完成，不用切到控制台。

## 第一步：创建 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 控制台](https://console.cloud.tencent.com/tcb) → 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](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started) 来连接你的 CloudBase 环境。

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


- 创建和部署云函数

- 查看函数日志和配置

- 管理环境变量

- 配置域名和路由


再配合 [CloudBase Skills](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/prompts/how-to-use)（安装命令：`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 云函数（官方文档）](https://docs.cloudbase.net/cloud-function/frameworks-examples/next)

- [CloudBase HTTP 云函数快速开始](https://docs.cloudbase.net/cloud-function/quickstart/httpfunc/nodejs)

- [CloudBase 自定义域名配置](https://docs.cloudbase.net/service/custom-domain)

- [CloudBase CLI 与 CI/CD 集成](https://docs.cloudbase.net/hosting/cli-devops)

- [CloudBase MCP 接入指南](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/getting-started)

- [CloudBase Skills 使用指南](https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/prompts/how-to-use)

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

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

Vercel？国内访问时好时坏。自己买台服务器？又得折腾 Nginx、PM2、SSL 那一套，太复杂。用腾讯云 CloudBase 的 HTTP 云函数。不用管服务器，不用装 Docker，把代码往上一推就能跑。15 分钟从一步步准备到线上访问，手把手图文教程

云计算

前端

开发工具

15分钟快速部署Next.js应用到腾讯云CloudBase，无需服务器运维。详细教程涵盖项目配置、scf_bootstrap编写、静态资源处理、CLI/MCP两种部署方式、自定义域名绑定、环境变量设置及GitHub Actions自动化部署，解决国内访问Vercel不稳定问题，特别提醒Windows用户注意换行符问题。

数据库

服务器

云函数

云托管

Windows

容器

路由

GitHub

Unix

2026采购季 | AI焕新·智启新局

domain

4核4G3M云服务器 新用户低至38元/年！

tcbr

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

15分钟快速部署Next.js应用到腾讯云CloudBase，无需服务器运维。详细教程涵盖项目配置、scf_bootstrap编写、静态资源处理、CLI/MCP两种部署方式、自定义域名绑定、环境变量设置及GitHub Actions自动化部署，解决国内访问Vercel不稳定问题，特别提醒Windows用户注意换行符问题...

手把手教你将 Next.js 应用部署到腾讯云 CloudBase-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐