想通过 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 更新部署即可；成功标志是新构建沿用原站点，而不是创建一个不相关的新项目。如果它误将子域名当作项目 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保存在项目根目录，后续更新可沿用原项目。- 重要部署已完成认领；出现失败时能从部署历史找到构建日志或下载配置。
