Windsurf Cascade App 部署教程

想用 Cascade 把网页项目部署上线？真正容易卡住的地方往往不是点击“部署”按钮，而是搞不清项目能否正常构建、看不懂部署状态，以及公开页面打不开时找不到正确的排查路径。跟着本文步骤操作，你不仅能获得一个可分享的公开站点，还能掌握如何认领项目、查看构建记录、恢复部署配置。

先提醒一下：App Deploys 目前仍为测试功能，主要用于预览和分享项目，不适合直接用于承载敏感数据的生产业务。当前使用的部署服务商为 Netlify，支持 Next.js、React、Vue、Svelte 以及静态 HTML、CSS、JavaScript 项目。部署时，项目代码会先上传至 Windsurf 服务器，再通过服务商账户完成构建和发布。

先认识一下 App Deploys 功能浮层：火箭图标对应部署功能，右侧的 Deploy 用于发起部署，View history 是查看历史记录的入口。标题旁的 BETA 标记说明该功能仍处于测试阶段。

部署前先确认三个条件

项目须能在本地正常构建。进入项目根目录，先运行项目原本的构建命令；常见 JavaScript 项目可尝试 npm run build。成功标志很简单：命令正常执行完毕，并生成构建产物。若在此步骤出现报错，请先在本地修复依赖、脚本或框架配置问题——远端部署不会帮你跳过本地构建的缺陷。

代码须适合公开预览。App Deploys 会上传项目文件并生成公开访问入口。提交前务必检查环境变量、测试密钥、内部地址和个人数据，确认仓库中不包含不应公开的内容。若项目必须依赖私有网络、付费资源或服务端机密，建议改用受控的正式部署方案。

账户额度须充足。免费方案每天可部署 1 次，同时保留 1 个未认领站点；Pro 方案每天可部署 10 次，同时保留 5 个未认领站点。团队版和企业版需连接团队的 Netlify 账户，入口由团队管理员开启。若看不到团队部署选项，请先联系管理员检查 Team Settings，不要反复发起部署。

从 Cascade 发起第一次部署

第一步：让 Cascade 识别项目并生成配置

入口位置：在 Windsurf 桌面端打开目标项目，进入 Cascade 对话区。主要操作：输入“将这个项目部署到 Netlify”这类明确指令即可，让 Cascade 处理当前项目。成功标志：界面出现部署配置已分析的状态，并开始创建 netlify.toml。失败处理：若 Cascade 未识别出框架，请检查当前工作区是否打开了正确的项目根目录，以及 package.json、构建脚本和框架目录是否齐全。

从下图可以看到，右侧先显示“Deployment config analyzed”，随后进入创建配置文件的状态。看到这两个节点，说明 Cascade 已从普通对话切换到实际部署流程。

第二步：确认文件上传和构建已排队

入口位置：在同一条 Cascade 部署对话中查看状态卡片即可。主要操作：等待项目文件上传完成，上传过程中请勿关闭工作区或重复发起部署。成功标志：状态卡片显示文件已全部上传、应用构建已排队，并在回复中给出公开站点地址。失败处理：若上传数量停滞不动，请检查网络连接和单个文件大小；若构建未进入队列，请返回上一步配置状态，核对构建命令、发布目录和 netlify.toml。

下图右上角的上传计数已走完，紧接着显示构建排队；正文区域同时给出了框架、子域名和上传结果。到这一步才算“部署请求已提交给服务商”，并不等于页面已构建成功。

第三步：打开公开页面检查实际结果

入口位置：在 Cascade 部署结果中查找公开站点地址，或从 App Deploys 历史记录进入对应项目。主要操作：打开页面后务必进行实际操作验证，不要仅看地址生成就认为完成。成功标志：页面能正常加载，样式、脚本和路由与本地预览一致。失败处理：若页面空白、资源缺失或刷新子路由后报错，请返回构建日志检查发布目录、静态资源路径和路由重写配置。

下图中的部署结果已在 Windsurf Preview 中打开。判断是否成功时，至少应检查首屏内容、一次按钮或输入操作，以及一个非首页路径；仅弹出浏览器窗口并不能证明应用功能正常。

公开后别忽略认领和配置文件

部署完成后会同时提供公开地址和认领入口。重要项目建议尽快认领到自己的 Netlify 账户中，这样才能直接查看服务商构建日志、管理站点设置并长期保留项目。未认领的部署可能过段时间被删除，请不要将未认领地址当作稳定的长期发布地址使用。

项目根目录中的 windsurf_deployment.yaml 保存着项目 ID、框架等再次部署所需的信息。后续更新时，在原项目中让 Cascade 更新部署即可；成功标志是新构建沿用原站点，而不是另创建一个不相关的项目。若 Cascade 误将子域名当作项目 ID，请明确要求它读取配置文件中的 project_id。

页面打不开时按可见信号排查

出现 Site not found

入口位置：打开刚生成的公开页面即可。主要操作：先确认错误页面是否明确显示 Site not found。成功标志：修复后同一页面能显示应用内容。失败处理：先从部署历史认领站点，再查看构建日志；将实际日志提供给 Cascade 分析，比只说“打不开”更容易定位构建命令、依赖或发布目录的问题。

这类页面是明确的失败信号，不要误以为是域名未生效而反复刷新。官方排查方向首先指向构建失败和部署记录。

构建失败但没有明确代码提示

入口位置：返回 Cascade 的构建状态页面，或前往已认领站点的服务商日志中查找。主要操作：需找到第一条真正导致退出的错误，不要只看最后一行的失败摘要。成功标志：本地构建和远端构建使用相同命令后均能通过。失败处理：依次检查本地构建、框架推荐目录、netlify.toml、环境变量和发布目录。框架代码本身的错误需在本地修复，App Deploys 不负责替代框架调试。

部署配置丢失或项目 ID 无法识别

入口位置：打开 App Deploys 的部署历史，在对应项目右侧展开更多菜单。主要操作：选择 Download config file，将下载的配置文件放回当前项目根目录即可。成功标志：配置文件中能找到与历史项目对应的项目 ID，Cascade 再次部署时能识别原项目。失败处理：若历史记录中也找不到项目，请先确认站点是否已认领、是否登录了同一账户，再决定是否创建新部署；不要随意填写项目 ID。

菜单中的 Download config file 即为恢复入口。其旁边还有删除操作，排查时请勿误点删除，否则原本可恢复的历史记录将被清除。

完成检查清单

• 本地构建命令正常结束，依赖和发布目录均无报错。
• 项目中没有密钥、内部地址或不应公开的数据。
• Cascade 显示配置分析完成、文件上传完成和构建已排队。
• 公开页面可正常打开，首屏、交互和非首页路径均已检查。
• windsurf_deployment.yaml 保存在项目根目录，后续更新可沿用原项目。
• 重要部署已认领；出现失败时能从部署历史找到构建日志或下载配置。