独立安装说明

若当前环境仅安装了本技能，请从 CloudBase 主入口启动，并对同级技能使用已发布的 cloudbase/references/... 路径。

• CloudBase 主入口：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
• 本技能原始源文件：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/web-development/SKILL.md

对于随本技能目录一同分发的文件，保留本地 references/... 路径。当本文件引用同级技能（例如 auth-tool 或 web-development）时，请使用该引用旁标注的独立回退 URL。

跨领域协议（代码变更或静态托管发布前必须遵守）：

• 变更安全协议：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-platform/references/protocols/change-safety-protocol.md
• 部署关卡：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-platform/references/protocols/deployment-gate.md

Web 开发

激活契约

首次使用本技能的适用场景

• 请求内容为实现、集成、调试、构建、部署或验证 Web 前端或静态网站。
• 设计方向已明确，或用户需求聚焦于工程执行而非视觉探索。
• 工作涉及 React、Vue、Vite、路由、浏览器端验证或 CloudBase Web 集成。

编码前须阅读（如满足以下任一条件）

• 任务涉及项目结构、框架约定、构建配置、部署、路由，或前端测试与验证流程。
• 请求包含 UI 实现，但视觉方向已固定；否则请先阅读 ui-design。

还需同步阅读

• 通用 React / Vue / Vite 指导 → frameworks.md
• 浏览器流程检查或页面验证 → browser-testing.md
• 登录流程 → ../auth-tool/SKILL.md（独立回退 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-tool/SKILL.md），再阅读 ../auth-web/SKILL.md（独立回退 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-web/SKILL.md）
• CloudBase 上的公众号 JSAPI 支付、原生二维码支付或微信 OAuth → ../cloudbase-wechat-integration/SKILL.md（独立回退 URL：https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-wechat-integration/SKILL.md；官方文档：https://docs.cloudbase.net/integration/introduce/index.md）
• CloudBase 数据库相关工作 → 对应的数据库技能

禁止使用场景

• 设定视觉方向、以原型为先导的设计工作，或纯美学探索。
• 小程序、原生 App 或仅后端服务。
• 微信支付或公众号 OAuth 的具体契约细节；应在识别 Web 表面后使用 cloudbase-wechat-integration。

常见错误 / 注意事项

• 未明确任务属于设计还是工程执行即开始实现。
• 将框架搭建、部署与 CloudBase 集成等关注点混入单一模糊变更中。
• 将云函数作为 Web 认证的默认解决方案。
• UI 或路由变更后跳过浏览器层级验证。
• History 模式 SPA 与 CloudBase 静态托管：使用 History 模式（React Router / Vue Router）部署单页应用时，未将静态托管的“404 错误文档”配置为 index.html。这会导致用户刷新或直接访问任意子路由时返回 NoSuchKey / 404 错误，因静态托管会尝试查找对应路径下的物理文件，而非交由 index.html 由 SPA 自行处理路由。
• 在已有应用中，未修复当前处理器和服务前，即转向 UI 重构或大范围代码库扫描。

工程宪章（不可协商）

这些规则优先于便利性。将其视为宣告“完成”前的强制门禁。

1. TypeScript — 不得压制类型系统

• 禁止使用 any 绕过类型错误。 禁止使用 : any、as any、@ts-ignore、@ts-nocheck 或无书面理由的 @ts-expect-error。any 会静默传播，彻底破坏本项目唯一拥有的编译期安全保障。
• 出现类型错误时，须修复根本原因：
  • 缺失或错误的库类型 → 安装 @types/...，或缩小导入范围，或为实际使用的数据结构编写精确的 interface / type。
  • 边界处结构确实未知（如 API 返回的 JSON、postMessage 载荷、window.* 注入）→ 使用 unknown 类型，并通过类型守卫（typeof、in、判别字段或 zod 等等效方案）进行收窄。
  • 第三方类型有误 → 在本地 .d.ts 文件中通过 declare module 扩展，而非使用 any。
  • 真正动态场景（如泛型事件总线）→ 使用带约束的泛型 ，而非 any。
• unknown + 类型收窄是可接受的逃生舱口；any 不是。
• 若确因极特殊原因无法避免某一行使用 any（极其罕见），须添加单行注释，明确说明为何必须如此及何种方式可消除该用法，以便审查者审计。
• ESLint 同理：不得随意添加 // eslint-disable 来屏蔽真实问题。应修复规则违规项，或在禁用前充分讨论。

2. 宣告完成前须自我验证

执行任何非平凡的代码或配置变更前，必须首先遵循 cloudbase-platform/references/protocols/change-safety-protocol.md 中定义的变更安全协议（声明影响 → 用户确认 → 变更后验证）。 执行任何静态托管发布或自定义域名操作前，须完成 cloudbase-platform/references/protocols/deployment-gate.md 中列出的全部检查项。

在无实证支持下声称“已实现”、“已修复”或“应该可以工作”，均不可接受。宣告完成前，必须实际运行验证步骤并报告结果。

静态 / 构建层（始终适用，如有）：

• tsc --noEmit（或 vue-tsc --noEmit）干净通过 —— 零错误，且未新增任何被抑制的诊断信息。
• eslint / 项目 Linter 在变更文件上通过。
• 项目构建命令（npm run build / pnpm build / vite build）成功完成，且未引入新的警告。
• 若存在单元测试且覆盖所修改区域，则测试必须全部通过。

运行时 / 浏览器层（只要变更影响渲染、路由、表单、认证或异步流程）：

• 使用 agent-browser 工具实际打开页面并复现用户可见流程。具体操作流程请参阅 browser-testing.md。
• 确认：目标路由可正常加载；您声称已修复的交互行为符合预期；未引入新的控制台错误；相邻所涉路由无回归问题。
• 记录所验证内容（路由、操作、预期结果、实际结果）。

仅当两层验证均通过后，方可宣告任务完成。若任一层无法在本地执行（例如受凭据限制、缺少后端、依赖付费 API），须明确说明并逐条列出尚未验证的具体步骤 —— 不得含糊其辞。

3. 不得掩盖失败

• 不得用 try { ... } catch {} 包裹失效逻辑以隐藏错误。
• 不得删除或跳过失败的测试以使 CI 通过 —— 应修复测试，或说明该测试本身有误并附理由修改测试。
• 不得以“代码能编译”为由标记任务完成。编译仅是最基本要求，而非目标。

何时使用本技能

本技能适用于如下 Web 工程工作：

• 实现 React 或 Vue 页面与组件
• 搭建或维护基于 Vite 的前端项目
• 处理路由、数据加载、表单及构建配置
• 执行浏览器端验证与冒烟检查
• 在项目需使用 CloudBase 能力时，集成 CloudBase Web SDK 与静态托管

禁止用于：

• 仅 UI 方向或视觉系统设计；请使用 ui-design
• 小程序开发；请使用 miniprogram-development
• 后端服务实现；请使用 cloudrun-development 或 cloud-functions

如何使用本技能（面向编码 Agent）

1. 明确执行层面

   • 确认任务属于框架搭建、页面实现、调试、部署、验证，还是 CloudBase 集成。
   • 将工作范围限定于实际 Web 应用层面，避免扩散至无关的后端变更。
   • 若工作区为已有应用且含待办事项（TODO），应视作定向修复任务，而非全新构建。

2. 遵循框架与构建规范

   • 若项目已有技术栈，优先沿用。
   • 对于新工作，默认采用 Vite 作为打包器，除非仓库或用户明确约束使用其他工具链。
   • 除非仓库已采用不同约定，否则将可复用的应用代码置于 src 下，构建输出置于 dist 下。
   • 在已有固定结构的应用中，应优先检查已承载业务逻辑的文件，而非通读宽泛文档：如 src/lib/backend.*、src/lib/auth.*、src/lib/*service.*、路由守卫，以及绑定至提交按钮的页面处理器。

3. 通过浏览器验证，而不仅限于代码阅读

   • 针对交互、路由、渲染或回归检查，使用 browser-testing.md 中定义的 agent-browser 工作流。
   • 在宣告前端工作完成前，优先对变更流程执行轻量级冒烟验证。

4. 将 CloudBase 视为集成分支

   • 仅当项目确实需要 CloudBase 平台能力时，才使用 CloudBase Web SDK 与静态托管指南。
   • 登录或身份提供商就绪性（provider readiness）应复用 auth-tool 和 auth-web，而非在此重复描述相关流程。

核心工作流

1. 选择正确的工程路径

• React / Vue 功能开发：在应用现有组件、路由与状态约定内实现
• 新建 Web 应用：默认首选 Vite，除非仓库已标准化使用其他工具链
• 调试与回归修复：在浏览器中复现问题，缩小至特定页面或交互，再打补丁
• CloudBase 集成：仅在基础前端路径明确后，再接入 Web SDK、认证、数据或静态托管

2. 使实现扎根于项目现实

• 遵循仓库的包管理器、脚本及 lint/test 模式
• 除非用户明确要求，否则避免重写框架
• 优先采用满足任务所需的最小可行页面/组件/配置变更
• 在基于 TODO 的应用中，直接完成现有实现，而非创建并行辅助模块、示例页面或脱离上下文的原型

3. 显式验证变更流程

• 如可用，运行相应的本地构建 / Lint / 类型检查 / 测试命令。tsc --noEmit 清洁通过与项目构建成功是最低门槛 —— 并非正确性的证明。
• 对于任何用户可见内容（路由、表单、渲染、认证、异步流程），须使用 agent-browser 在浏览器中打开受影响页面或流程。仅靠代码阅读不足以构成有效证据 —— 详见上方“工程宪章”。
• 记录所验证内容：路由、操作、预期结果、实际结果，以及任何剩余缺口。

CloudBase Web 集成

仅当 Web 项目需要 CloudBase 平台能力时，才使用本节内容。

Web SDK 规则

• 对于 React、Vue、Vite 及其他基于打包器的项目，优先使用 npm 安装
• 仅对静态 HTML 页面、快速演示、嵌入式代码片段或 README 示例使用 CDN
• 仅使用 CloudBase Web SDK 文档中明确记载的 API；不得自行发明方法或选项
• 复用共享的 app 或 auth 实例，避免每次调用都重新初始化
• 若用户仅提供环境别名、昵称或其他简写形式，须在编写 SDK 初始化代码、控制台链接或配置文件前，将其解析为规范的完整 EnvId。禁止将类别名的短格式直接传入 cloudbase.init({ env })。

认证边界

• 认证必须使用 CloudBase SDK 内置功能
• 不得将 Web 登录逻辑移至云函数中
• 对于身份提供商就绪性、登录方式配置或可发布密钥问题，请转至 auth-tool 和 auth-web

静态托管默认配置

• 部署前必须构建

• 优先使用相对资源路径以确保静态托管兼容性

• 当项目缺乏服务端路由重写能力时，默认启用哈希路由（hash routing）

• 若用户未指定根路径，应默认避免直接部署至站点根目录

• SPA 路由（History 模式）：当使用 React Router / Vue Router 的 History 模式（非哈希模式）时，须将 CloudBase 静态托管的“404 错误文档”配置为 index.html。否则，用户刷新或直接访问任意子路由时，静态托管会因查找对应路径的物理文件失败而返回 NoSuchKey / 404 错误，而非交由 index.html 由 SPA 处理路由。

  请使用 MCP 工具执行该配置：

  manageHosting({ action: "setWebsiteDocument", indexDocument: "index.html", errorDocument: "index.html" })
  

  随后通过以下命令验证：

  queryHosting({ action: "websiteConfig" })
  

CloudBase 快速入门

// npm install @cloudbase/js-sdk
import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "your-full-env-id", // 由 envQuery 或控制台解析得到的规范完整 CloudBase 环境 ID
});

const auth = app.auth();