Vibe Vibe

主题

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 控制台，用微信扫码或腾讯云账号登录。如果是第一次使用腾讯云，需要完成实名认证。

image-20260227003947136

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

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

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

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

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

image-20260227005154181

配置构建设置 ​

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

image-20260227005228223

框架预设选 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

配置环境变量 ​

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

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

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

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

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

环境变量修改后需要重新部署

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

选择加速区域 ​

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

image-20260227005154181

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

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

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

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

image-20260302003046402

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

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

error engine "node" is incompatible with this module

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

image-20260227005254177

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

部署成功：拿到链接 ​

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

image-20260302003255608

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

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

预览链接的限制

如果你选的是"全球（不含中国大陆）"加速区域，默认域名可能有访问限制（3 小时有效期）。绑定自定义域名后就没有这个限制了。域名配置详见 第十三章。

常见构建失败排查 ​

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

报错关键词原因解决方案
engine "node" is incompatibleNode 版本不匹配在设置里调整 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 会详细展开。

使用部署 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

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

下一步

EdgeOne 部署搞定了。如果你的用户主要在海外，或者想了解更多平台选择，继续看 12.2 部署到类 Vercel 平台。