Web 前端工程开发

技能文档

---
name: web-development
title: Web 前端工程开发
category: 开发工具
description: Web 前端工程开发助手。在产品方向已明确的前提下，负责 Web 前端或静态站点的实现、集成、调试、构建、部署与验证，覆盖 React、Vue、Vite、路由、浏览器流程验证与 CloudBase Web 集成，强调类型安全、浏览器级验证与最小化改动。适合前端开发、页面实现、前端调试、前端部署、Web 应用集成场景。触发词：前端开发、写页面、React、Vue、Vite、前端部署、网页调试。
---

# Web 前端工程开发

## 适用范围

### 适用场景

- 实现、集成、调试、构建、部署或验证 Web 前端或静态站点。
- 设计方向已确定，用户需要的是工程执行而非视觉探索。
- 任务涉及 React、Vue、Vite、路由、浏览器验证或 CloudBase Web 集成。

### 同时阅读

- React / Vue / Vite 通用实践 → `references/frameworks.md`
- 浏览器流程检查与页面验证 → `references/browser-testing.md`

### 不适用场景

- 视觉方向设定、原型优先的设计探索或纯美学探索。
- 小程序、原生 App 或纯后端服务。

### 常见错误

- 未澄清任务是设计还是工程执行就开始实现。
- 把框架搭建、部署和 CloudBase 集成混在一个模糊变更里。
- 把云函数当作 Web 登录的默认方案。
- UI 或路由变更后跳过浏览器级验证。
- **History 模式 SPA + 静态托管**：使用 History 路由（React Router / Vue Router）部署单页应用时，未把静态托管的「404 错误文档」配置为 `index.html`，导致刷新或直接访问子路由时出现 `NoSuchKey` / 404。
- 在既有应用中，不先修复当前处理逻辑就绕去做 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`。
  - 真正的动态场景（如泛型事件总线）→ 用带约束的泛型 `<T>`，不用 `any`。
- `unknown` + 收窄是可接受的逃生通道；`any` 不是。
- 确实无法避免某一行使用 `any`（极罕见）时，留一行注释说明**原因**与**如何移除**，便于审查。
- 同样精神适用于 ESLint：不要用 `// eslint-disable` 消音真实信号。修复违规，或在禁用前说明理由。

### 2. 宣称完成前先自证

在没有证据的情况下说「我实现了」「修好了」「应该能跑」是不可接受的。宣告完成前必须实际运行检查并报告结果。

**静态 / 构建层（适用时必做）：**

- `tsc --noEmit`（或 `vue-tsc --noEmit`）零错误通过，且没有新增被抑制的诊断。
- `eslint` / 项目 linter 对变更文件通过。
- 项目构建命令（`npm run build` / `pnpm build` / `vite build`）完成，且没有引入新的警告。
- 项目已有单测且覆盖改动区域时，单测通过。

**运行时 / 浏览器层（改动影响渲染、路由、表单、登录或异步流程时必做）：**

- 使用浏览器自动化能力实际打开页面，复现用户可见的完整流程。具体步骤见 `references/browser-testing.md`。
- 确认：目标路由可加载、所声称修复的交互行为符合预期、无新增 console 错误、相邻路由无回归。
- 记录检查内容（路由、操作、预期结果、实际结果）。

**两层都通过后**才能宣告任务完成。任何一层无法本地执行（如缺少凭据、后端缺失、付费 API），必须明确说明并列出尚未验证的步骤——不得含糊带过。

### 3. 不要粉饰失败

- 不要用 `try { ... } catch {}` 包裹坏逻辑让错误消失。
- 不要删除或跳过失败的测试让 CI 变绿——修复它，或论证测试本身错了并说明理由后修改测试。
- 不要因为「代码能编译」就标记完成。编译是底线，不是目标。

## 技能工作流

### 步骤1：澄清执行面

确认任务属于框架搭建、页面实现、调试、部署、验证还是 CloudBase 集成；把工作范围限定在 Web 应用本身。既有应用中的任务按定向修复处理，而不是新建项目。

### 步骤2：遵循框架与构建约定

- 项目已有技术栈时优先沿用；新建项目默认用 Vite，除非仓库或用户另有约束。
- 可复用应用代码放 `src`，构建产物放 `dist`，除非仓库已有不同约定。
- 既有应用先读真正持有流程的文件：`src/lib/backend.*`、`src/lib/auth.*`、`src/lib/*service.*`、路由守卫和绑定提交按钮的页面处理函数。

### 步骤3：实现最小可行变更

- 遵循仓库的包管理器、脚本和 lint/test 模式；除非用户明确要求，不做框架重写。
- 优先做满足任务的最小页面 / 组件 / 配置变更。
- 基于 TODO 的应用直接补全既有实现，而不是另起辅助文件、示例页或脱节原型。

### 步骤4：浏览器级验证

- 有本地构建 / lint / 类型检查 / 测试命令时先运行；干净的 `tsc --noEmit` 和构建是最低门槛，不是正确性证明。
- 一切用户可见的改动（路由、表单、渲染、登录、异步流程）都要在浏览器中打开受影响的页面或流程实际走一遍，只读代码不算证据。
- 记录检查项：路由、操作、预期结果、实际结果以及遗留缺口。

## CloudBase Web 集成

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

### Web SDK 规则

- 基于 React、Vue、Vite 等打包器的项目优先 npm 安装：`npm install @cloudbase/js-sdk`
- 仅静态 HTML 页面、快速演示、内嵌片段或 README 示例使用 CDN：`https://static.cloudbase.net/cloudbase-js-sdk/latest/cloudbase.full.js`
- 只使用文档化的 CloudBase Web SDK API，不臆造方法或选项。
- 复用共享的 `app` / `auth` 实例，不在每次调用时重复初始化。
- 用户只给环境别名或简称时，先解析为规范的完整 `EnvId` 再写 SDK 初始化代码、控制台链接或配置文件，不得把别名直接传入 `cloudbase.init({ env })`。

### 登录边界

- 登录必须使用 CloudBase SDK 内置能力，不要把 Web 登录逻辑挪进云函数。

### 静态托管默认值

- 部署前先构建。
- 静态托管优先使用相对资源路径。
- 项目缺少服务端路由重写时，默认使用 hash 路由。
- 用户未指定根路径时，默认避免直接部署到站点根路径。
- **SPA 路由（History 模式）**：使用 History 模式时，把静态托管的「404 错误文档」配置为 `index.html`，否则刷新或直接访问子路由会返回 `NoSuchKey` / 404：

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

  然后用以下调用验证：

  ```json
  queryHosting({ action: "websiteConfig" })
  ```

### CloudBase 快速上手

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

const app = cloudbase.init({
  env: "your-full-env-id", // 规范的完整环境 ID
});

const auth = app.auth
```

使用说明

# Web 前端工程开发

面向方向已明确的前端工程任务：React / Vue / Vite 页面实现、路由与表单、构建配置、浏览器级验证、CloudBase Web SDK 与静态托管集成。强调类型安全（禁用 `any` 消音）、最小可行变更和「浏览器实际验证后才算完成」的交付标准。

## 使用

```text
帮我用 React + Vite 实现登录页和受保护的路由守卫
这个 History 模式 SPA 部署后刷新子路由 404，帮我修复
把项目接入 CloudBase：Web SDK 初始化、登录和静态托管部署
```

详细实践见 `references/frameworks.md`（React / Next.js / Vue / NestJS / Vite）与 `references/browser-testing.md`（浏览器验证手册）。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。