---
title: "12.1 部署到 EdgeOne Pages"
---

# 12.1 部署到 EdgeOne Pages

> **本节目标**：把你的 Next.js 项目部署到腾讯云 EdgeOne Pages，获得一个公网可访问的链接。

小明的朋友发来消息："你上次给我看的那个链接又打不开了。"小明这才意识到，Cloudflare Tunnel 的临时链接关了终端就没了。他需要一个**永久在线**的地址——不管自己的电脑开不开机，任何人随时都能打开。

这就是"部署"要做的事。部署的本质很简单：**让云端的电脑替你跑你本地跑过的那些命令**。你在本地 `pnpm install` 装依赖、`pnpm build` 构建项目，部署平台做的是完全一样的事——只不过它 24 小时不关机，而且有一个公网地址。

EdgeOne Pages 是腾讯云的边缘部署平台，国内访问速度快，对 Next.js 支持好，免费额度足够个人项目使用。小明决定从这里开始。

## 部署前的三个确认

在点击"部署"之前，小明需要确认三件事。这不是走流程，每一项都有实际原因。

**第一，代码已经推到 GitHub。** 部署平台需要从 GitHub 拉取你的代码。如果代码只在本地，平台拿不到。这一步在第十一章已经完成了。

**第二，本地 `pnpm build` 能成功。** 这是最重要的一步。如果本地构建都跑不通，云端一定也跑不通——云端做的事和你本地一模一样。在终端里运行一次 `pnpm build`，看到 "Build completed" 就说明没问题。

**第三，记录好 `.env` 里的环境变量。** 你在第六章学过，`.env` 文件被 `.gitignore` 排除了，不会上传到 GitHub。这意味着部署平台拉到的代码里没有数据库密码、没有认证密钥——你需要在平台上手动配置这些变量。现在打开本地的 `.env` 文件，确认你知道里面有哪些变量、每个变量的值是什么。

## 注册并连接 GitHub

打开 [EdgeOne Pages 控制台](https://console.cloud.tencent.com/edgeone/pages)，用微信扫码或腾讯云账号登录。如果是第一次使用腾讯云，需要完成实名认证。

![image-20260227003947136](/images/Advanced/image-20260227003947136.png)

点击 **导入 Git** 仓库，选择 **连接 GitHub**。

首次连接会跳转到 GitHub 的授权页面。这里有一个选择：授权所有仓库，还是只授权特定仓库？

小明选了"Only select repositories"，只授权了"个人豆瓣"这一个仓库。这是**最小权限原则**——只给平台它需要的权限，不多给。如果以后要部署其他项目，再回来加授权就行。这个习惯在第八章安全那一节就提过，到了部署环节同样适用。

授权完成后，你能看到自己的仓库列表。选择要部署的项目，点击 **下一步**。

当然，点击直接上传也是可以的，平台会通常会自动识别项目架构。

![image-20260227005154181](/images/Advanced/image-20260227005154181.png)

## 配置构建设置

这一步是告诉平台"怎么构建你的项目"。EdgeOne 会根据你选的框架自动填充推荐配置，但你需要理解每一项的含义，这样出问题时才知道去哪里改。

![image-20260227005228223](/images/Advanced/image-20260227005228223.png)

**框架预设**选 Next.js。选了之后，平台会自动帮你填好构建命令和输出目录——就像你在手机上打开 .pdf 文件时系统自动用 PDF 阅读器打开一样，平台识别了你用 Next.js，就自动知道该怎么构建。

**根目录**保持默认的 `./`。如果你的项目代码不在仓库根目录（比如在 `apps/web/` 子目录下），才需要改这个。小明的项目就在根目录，不用动。

**构建命令**是 `pnpm build`（或 `npm run build`）。这就是你在本地跑过的那个命令——平台在云端执行完全一样的操作。

**输出目录**是 `.next`。这是 Next.js 构建后生成文件的位置，平台需要知道去哪里找构建产物。

**Node 版本**——EdgeOne 通常默认是 Node 22，大多数 Next.js 项目直接用默认值就能构建通过。一般先不改，**只有当日志里出现 Node 版本不兼容报错时，再改成和你本地一致的版本**。

![image-20260227005254177](/images/Advanced/image-20260227005254177.png)

## 配置环境变量

在构建设置页面下方，找到 **环境变量** 区域。

还记得刚才说的吗？`.env` 文件没有上传到 GitHub，所以你需要在这里手动把变量填进来。EdgeOne Pages 支持**批量导入**——直接把 `.env` 文件的内容粘贴进去，平台会自动解析成键值对![image-20260227005320209](/images/Advanced/image-20260227005320209.png)。



小明的项目需要这几个变量：

```bash
DATABASE_URL="postgresql://..."        # 数据库连接字符串，没有它应用连不上数据库
BETTER_AUTH_SECRET="xxx"               # 认证密钥，没有它登录功能会报错
BETTER_AUTH_URL="https://你的域名"      # 认证回调地址，先留空，部署成功拿到链接后再改
```

每个变量都有它的作用。`DATABASE_URL` 缺了，应用启动时就会报 "Cannot connect to database"；`BETTER_AUTH_SECRET` 缺了，用户登录会直接 500 错误。如果你不确定需要哪些变量，打开本地的 `.env` 文件，里面有的这里都要有。

::: tip 环境变量修改后需要重新部署
修改环境变量不会自动生效。你需要点击"重新部署"，平台才会用新的变量值重新构建。
:::

## 选择加速区域

这是国内部署平台特有的一步，和 ICP 备案有关。

![image-20260227005154181](/images/Advanced/image-20260227005154181.png)

简单来说：如果你选了包含"中国大陆"的加速区域，就需要 ICP 备案。你在很多国内网站底部都能看到一串"京ICP备xxxxxxxx号"之类的文字，那就是 ICP 备案号。国内法规要求，服务器在中国大陆的网站必须完成备案才能对外访问。个人也可以申请，但需要一到两周的审核时间。

小明不想等，选了**"全球（不含中国大陆）"**。这个选项不需要备案，部署后立刻就能用。虽然名字里说"不含中国大陆"，但绑定自定义域名后国内也能正常访问——域名配置的事留到第十三章再说。

## （可选）如果构建失败，怎么排查

一切配置完毕后，正常情况下首次部署会直接成功。

![image-20260302003046402](/images/Advanced/image-20260302003046402.png)

如果你也遇到红色的 **Failed**，再看这一小节就行。**构建日志是最重要的信息源——答案通常在最后几行。**

例如，常见的一类报错是：

```
error engine "node" is incompatible with this module
```

这表示 Node 版本不兼容。处理方式很简单：回到构建设置，把 Node 版本改成和项目要求一致，然后点击**重新部署**。

![image-20260227005254177](/images/Advanced/image-20260227005254177.png)

重新部署后，通常就会顺利走到绿色的 **Success**。

## 部署成功：拿到链接

构建成功后，平台生成了一个预览链接，格式类似 `xxx.edgeone.dev`。

![image-20260302003255608](/images/Advanced/image-20260302003255608.png)

小明点开链接，看到了自己的"个人豆瓣"——和本地一模一样，但这次是在公网上。他把链接发给朋友，朋友秒开了页面，回了一句："终于能打开了！"

这是整个教程到目前为止最有成就感的时刻：**你写的代码，现在全世界都能访问了。**

::: warning 预览链接的限制
如果你选的是"全球（不含中国大陆）"加速区域，默认域名可能有访问限制（3 小时有效期）。**绑定自定义域名后就没有这个限制了**。域名配置详见 [第十三章](../13-domain-dns/index.md)。
:::

## 常见构建失败排查

小明的 Node 版本问题只是最常见的一种。如果你也遇到了构建失败，先看日志最后几行的报错关键词：

| 报错关键词 | 原因 | 解决方案 |
|-----------|------|---------|
| `engine "node" is incompatible` | Node 版本不匹配 | 在设置里调整 Node 版本 |
| `Cannot find module` | 依赖没装上 | 检查 `package.json` 和锁文件是否提交到 GitHub |
| `DATABASE_URL is not defined` | 环境变量没配 | 在环境变量页面添加 |
| `Build failed` + 无具体信息 | 构建命令错误 | 确认构建命令和本地一致 |
| `ENOENT: no such file` | 路径错误 | 检查根目录配置 |

遇到看不懂的报错？把日志复制给 Claude Code，让它帮你诊断。构建日志里的信息通常足够定位问题。

## 推送即部署

连接 GitHub 后，每次你 `git push` 到主分支，EdgeOne Pages 会自动触发重新部署。你不需要手动操作——这就是 CI/CD 的雏形，我们在 [12.3](./03-cicd-automation.md) 会详细展开。

## 使用部署 Skill

本教程提供了 EdgeOne 部署 Skill，安装后告诉 Claude Code "帮我把项目部署到 EdgeOne Pages"，它会引导你完成整个流程。

安装方式：把下面的链接发给 Claude Code，它会自动识别并安装这个 Skill：

```
https://cnb.cool/nfeyre/default-dev-env/-/git/raw/main/.claude/skills/edgeone-deploy/SKILL.md
```

但理解上面这些手动步骤仍然重要——当自动化出问题时，你需要知道去哪里排查。



---

::: info 下一步
EdgeOne 部署搞定了。如果你的用户主要在海外，或者想了解更多平台选择，继续看 [12.2 部署到类 Vercel 平台](./02-deploy-vercel-platforms.md)。
:::