腾讯云 CloudBase Web 开发套件

具体问题

在现代 Web 前端开发中，开发者经常面临一系列工程化挑战：如何为 React、Vue 或 Vite 项目建立健壮的初始结构？如何处理单页应用的路由配置，避免用户刷新时出现 404 错误？如何确保构建产物在浏览器中正确运行，并与腾讯云 CloudBase 等平台无缝集成？这些工作涉及框架选型、构建工具链、路由策略、运行时验证以及云服务 SDK 集成，任何一个环节的疏忽都可能导致部署失败或用户体验问题。

技能如何工作

该技能提供了一套专注于工程执行的指南，其核心能力与关键步骤如下：

1. 明确执行范围：首先将任务分类为框架搭建、页面实现、调试、部署、验证或 CloudBase 集成，确保工作聚焦于 Web 应用层，避免无谓的后端或设计侧蔓延。
2. 遵循框架与构建约定：支持 React、Vue 等主流框架，并默认使用 Vite 作为构建工具。在现有仓库中，优先遵循已有的包管理器、脚本和目录结构，实施最小必要的变更。
3. 处理路由与部署细节：特别强调在使用 History 模式的路由（如 React Router 或 Vue Router）时，必须配置 CloudBase 静态托管的“404 错误文档”为 index.html，这是避免 NoSuchKey 错误的关键。同时建议新项目在无服务端重写时默认采用 Hash 路由。
4. 集成 CloudBase 能力：仅在项目需要云平台特性时引入。指导使用 npm 安装 @cloudbase/js-sdk，并遵循认证边界——登录逻辑应使用 SDK 内置功能，而非云函数。要求将环境 ID 解析为标准格式再传入初始化代码。
5. 强制工程验证：这是该技能的核心纪律。任何变更都必须通过两层验证：

静态/构建层：运行 tsc --noEmit（或 vue-tsc --noEmit）、项目 Linter 和构建命令，确保无新增错误。
运行时/浏览器层：使用 agent-browser 工具实际打开页面，重现用户流程，检查目标路由加载、交互行为和控制台错误。
只有两层验证均通过，才能声明任务完成。这杜绝了“代码能编译就行”的草率做法。

适用边界与注意点

该技能有明确的适用范围和不可妥协的原则：

• 不适用场景：它不用于 UI 视觉方向或原型设计（应使用 ui-design 技能）、小程序开发、原生应用或纯后端服务。当任务涉及界面样式调整时，必须先加载 ui-design 技能并输出设计规范。
• 常见陷阱：在 History 模式下部署到 CloudBase 静态托管而未配置错误文档；在 UI 变更后跳过浏览器验证；将 Web 登录逻辑移入云函数；或为了通过编译而滥用 try...catch 或忽略测试。
• 非协商的工程宪法：

禁止使用 any 类型：必须使用 unknown 结合类型守卫来处理未知数据，而非绕过类型系统。
自我验证：声明“已完成”前必须提供实际验证证据，包括构建日志和浏览器检查结果。
* 不掩盖失败：不得静默捕获错误、删除失败测试或仅以编译通过作为完成标准。