从本地运行到上线：第一版产品的部署流程

电脑上能打开的 localhost 地址，只在当前访问者自己的设备上有意义。把这个地址发给朋友，对方不会连到你的开发服务。

让别人使用前，需要把前端页面和服务端处理部署到可访问的环境。示例中的长文内容整理工具调用了模型 API，处理请求的服务端也必须能运行，不能只上传页面文件。

这篇继续使用系列中的教学示例。假定它已经完成本地调试与验收，接下来检查它到了线上是否仍能完成同一个任务。

先确认部署的是什么#

不同产品需要的运行条件不一样。部署前先检查项目是否只有静态页面，是否需要服务端接口，以及任务通常运行多久。

项目特点	可以考虑的部署方式	重点核对
只有静态页面	静态托管	构建命令与输出目录
页面加短时服务端请求	支持当前框架的托管平台	运行时、超时、依赖和费用
长时间生成或批量任务	后台任务服务、容器或其他合适运行环境	队列、任务状态和结果获取
已有独立服务端	前端托管加现有后端	接口地址、跨域和访问控制

Vercel、Cloudflare 等平台都有各自支持的框架与运行限制。选型时先核对项目依赖和任务要求，不要仅凭“免费”决定。

例如，摘要生成的耗时如果可能超过部署平台的请求执行上限，就需要调整超时或任务方式。超时后让用户一直点重试，可能产生更多调用费用。

下面以 Vercel 为流程示例，具体可用能力与费用按所用套餐及当前官方文档确认。

部署前先在本地构建#

开发服务能运行，构建仍可能失败。以采用 pnpm 且定义了相应脚本的项目为例：

1
pnpm build

如果项目定义了类型检查和测试，也按项目约定运行。构建失败时先处理本地报错，检查运行时版本、依赖和缺失配置，再去线上复测。

准备上传的文件清单也要检查：代码、锁文件和必要的静态资源应在版本中，实际密钥、本地缓存和无关资料不要一起上传。仓库已经跟踪的敏感文件，需要单独处理，添加忽略规则并不能撤回之前的内容。

如果使用 Git 集成部署，确认远程仓库包含准备发布的版本。许多平台也支持命令行部署，GitHub 并非所有部署方式的必需条件。

配置构建和运行环境#

创建项目时，核对仓库、项目根目录、框架、构建命令、输出目录和运行时版本。平台自动识别的结果可以作为起点，但仍要对照项目配置。

长文整理工具还需要模型服务地址、模型名称和服务密钥。把真实值填写到对应的服务端环境配置里，变量名应与代码读取的名称完全一致。不要把本地含密钥的配置文件上传到仓库。

Vercel 的环境变量可以分别作用于 Development、Preview 和 Production。测试环境也要配置它实际使用的变量，最好使用独立的测试资源，避免测试请求影响生产数据和额度。

官方文档明确说明：环境变量修改不会改变过去的部署，只作用于新部署。保存配置后，需要触发新部署，再检查变量是否生效。

看清首次部署与预览部署的区别#

已有 Vercel 项目通常可以通过非生产分支等方式创建 Preview 部署，先测试再发布。新项目有一个例外：按当前官方文档，首次部署会进入 Production，包括首次导入 Git 仓库的情况。

因此，第一次创建项目也要按公开上线准备：只使用获准公开的内容，配置合适的访问控制，确认服务端调用限制。后续预览链接是否需要登录、哪些人能访问，取决于项目的部署保护设置。

部署结束后，记录平台生成的地址、环境和对应版本。构建日志成功，只说明部署过程通过；还没有证明摘要接口能处理真实输入。

在线上重做一次验收#

打开线上地址，使用与本地验收相同的一份测试文章。检查三个输出字段、复制行为和失败提示。再换一个未登录开发平台的浏览器窗口，确认目标用户能够访问；如果本来就设置了访问限制，则检查受邀用户的访问方式。

1
[ ] 页面和静态资源正常加载。
2
[ ] 服务端接口处理的是实际输入，生产路径没有返回模拟数据。
3
[ ] 模型调用成功，输出字段与内容符合要求。
4
[ ] 无效输入、超时和服务端限制有可理解的提示。
5
[ ] 浏览器产物、响应和客户端日志不包含服务密钥。
6
[ ] 服务端日志能对应请求，且不记录完整用户原文。
7
[ ] 手机能够完成输入、查看和复制。
8
[ ] 部署的版本及验证时间有记录。

“线上页面返回 200”和“用户完成任务”是两个不同的检查。一个正常显示首页、但提交就报错的网站，仍不能交给用户使用。

本地正常、线上失败时查哪里#

先看构建日志，再看失败请求对应的运行日志。两类日志分别回答“能否构建”和“运行时发生了什么”。

现象	优先排查
构建失败	版本、依赖、构建命令、根目录和构建时配置
页面正常，模型调用失败	服务端变量、供应商响应和运行时支持
图片或其他文件丢失	文件是否进入版本、路径及大小写是否一致
请求经常超时	上游耗时与平台执行限制
预览正常，生产失败	两个环境的配置和资源是否相同
部分用户无法打开	部署保护、网络访问和域名解析

比如，本地 .env 存在，线上平台却没有对应变量，模型请求就可能失败；也可能是变量只配在 Preview，没有配在 Production。检查配置作用的环境，比重复修改业务代码更有针对性。

再连接自定义域名#

平台地址上的主流程通过后，再添加自己的域名。按平台给出的 DNS 记录配置，确认域名验证和 HTTPS 证书状态，并用自定义域名重新提交一次任务。

域名绑定可能影响应用的来源校验、登录回调和其他地址配置。即使第一版没有登录，也要核对接口请求有没有写死原来的平台地址。

如果涉及备案、平台审核或目标市场的其他要求，按实际服务地点与产品形态确认。选择某个平台并不能自动免除这些要求。

留一个能恢复服务的版本#

出现线上故障时，版本回退可以先恢复到已知可用的部署，再排查原因。不过，回退代码不会撤销已写入的数据，也不会取消已发出的消息或调用费用。

Vercel 的 Instant Rollback 可回到符合条件的旧生产部署，可选范围受套餐限制。旧部署使用旧构建及其配置，外部 API 和数据库却可能已经变化，恢复后还要检查兼容性。

还有一处操作细节：按当前官方文档，Instant Rollback 后会关闭生产域名的自动分配。修复完成后，需要通过相应的恢复或提升部署操作恢复正常发布流程，不能假设下一次推送一定会替换线上版本。

保存可用版本、配置项清单和关键检查步骤，再安排首批用户测试。下一篇会观察用户能否完成任务，并据此选择下一轮修改。