构建标准

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 构建, 编译, 打包, build
---

# 构建标准规范 (BUILD STANDARDS)

> **强制执行**：所有构建过程必须严格遵守此规范，不得违反。

## &#128680; 核心原则

1. **零容忍原则**：任何构建错误都不能被忽略
2. **缓存清理**：每次构建前必须清理缓存
3. **完整验证**：构建后必须验证产物
4. **环境隔离**：开发和构建环境严格分离

## &#128203; 构建流程标准

### 1. 预构建检查清单

在执行构建前，必须完成以下检查：

- [ ] 代码已提交到 Git
- [ ] 无未解决的类型错误
- [ ] 所有组件导出正确
- [ ] 环境变量已配置
- [ ] 依赖已安装（`pnpm install`）

### 2. 标准构建命令

```bash
# 方式1：使用项目脚本（推荐）
pnpm run build

# 方式2：手动执行（不推荐，除非调试）
rm -rf .next
pnpm run build
```

**禁止使用**：
- ❌ `npx next build`（绕过了项目脚本）
- ❌ 不清理缓存直接构建
- ❌ 使用 `--no-lint` 等跳过检查的参数

### 3. 构建验证标准

构建完成后，必须验证以下项目：

#### 3.1 构建状态检查

```bash
# 检查构建产物是否存在
ls -la .next/BUILD_ID

# 检查构建日志
tail -50 .next/build-manifest.json
```

**验证标准**：
- ✅ `.next/BUILD_ID` 文件存在
- ✅ 构建日志中无 ERROR 级别错误
- ✅ 构建时间合理（不超过 5 分钟）

#### 3.2 页面生成验证

```bash
# 检查关键页面是否生成
ls -la .next/server/app/
```

**必须生成的页面**：
- ✅ `/admin/dashboard`
- ✅ `/admin/changelog`
- ✅ `/login`
- ✅ 所有 API 路由

#### 3.3 静态资源验证

```bash
# 检查静态资源
ls -la .next/static/
```

**验证标准**：
- ✅ CSS 文件存在
- ✅ JS 文件存在
- ✅ 字体文件存在

## &#128295; 常见错误处理

### 错误1：组件导出错误

**错误信息**：
```
Export ChangelogWidget doesn't exist in target module
```

**处理流程**：
1. 定位导出文件（如 `src/components/changelog/index.ts`）
2. 确认组件文件存在
3. 确认导出语句正确
4. 重新构建

**禁止行为**：
- ❌ 注释掉导出来绕过错误
- ❌ 使用 `any` 类型来规避类型检查

### 错误2：TypeScript 类型错误

**错误信息**：
```
Type error: Property 'xxx' does not exist on type 'yyy'
```

**处理流程**：
1. 修复类型定义
2. 更新类型导入
3. 确保类型一致
4. 重新构建

**临时方案（仅限紧急情况）**：
```typescript
// next.config.ts
typescript: {
  ignoreBuildErrors: true, // 仅在紧急情况下使用
}
```

**注意**：临时方案必须在后续版本中修复。

### 错误3：模块未找到

**错误信息**：
```
Module not found: Can't resolve '@/components/xxx'
```

**处理流程**：
1. 检查路径别名配置（`tsconfig.json`）
2. 确认文件路径正确
3. 检查文件大小写
4. 重新构建

## &#128230; 构建产物标准

### 目录结构

```
.next/
├── BUILD_ID          # 构建ID，必须存在
├── build-manifest.json  # 构建清单
├── server/           # 服务端代码
│   ├── app/         # 页面代码
│   └── api/         # API路由
├── static/          # 静态资源
│   ├── css/         # 样式文件
│   ├── js/          # JavaScript文件
│   └── _next/       # Next.js资源
└── cache/           # 缓存文件
```

### 文件大小限制

- **单个 CSS 文件**：不超过 500KB
- **单个 JS 文件**：不超过 2MB
- **构建总大小**：不超过 100MB

## &#128640; 部署前验证

在部署到生产环境前，必须执行：

```bash
# 1. 清理缓存并构建
rm -rf .next
pnpm run build

# 2. 验证构建产物
ls -la .next/BUILD_ID

# 3. 启动预览服务
pnpm run start

# 4. 验证服务响应
curl -I http://localhost:5000

# 5. 验证关键页面
curl http://localhost:5000/admin/dashboard
curl http://localhost:5000/admin/changelog
```

## &#128221; 构建日志规范

### 日志记录

所有构建过程必须记录日志：

```bash
# 构建日志
pnpm run build > /app/work/logs/bypass/build.log 2>&1
```

### 日志分析

构建日志中不得包含：
- ❌ ERROR 级别错误
- ❌ Fatal 错误
- ❌ Build failed

允许的警告：
- ⚠️ Warning（但不影响构建）
- ⚠️ Deprecated（仅限已知兼容问题）

## &#128274; 质量门禁

### 必须通过的检查

1. **编译检查**：`npx tsc --noEmit`（如果类型检查未禁用）
2. **构建检查**：`pnpm run build` 成功
3. **产物检查**：所有必需文件存在
4. **功能检查**：核心功能可访问

### 质量标准

| 检查项 | 标准 | 状态 |
|--------|------|------|
| 构建成功 | 100% 通过 | ✅ 强制 |
| 类型错误 | 0 个 | ✅ 强制 |
| 页面生成 | 全部生成 | ✅ 强制 |
| 静态资源 | 正常加载 | ✅ 强制 |
| 启动时间 | < 2 秒 | ⚠️ 推荐 |

## &#128204; 违规处理

### 轻微违规

- **定义**：构建警告但不影响功能
- **处理**：记录问题，在下个版本修复
- **示例**：Deprecated 警告

### 严重违规

- **定义**：构建失败或功能异常
- **处理**：立即修复，不得合并代码
- **示例**：组件导出错误、类型错误

### 极其严重违规

- **定义**：绕过构建检查强制部署
- **处理**：立即回滚，全面审计
- **示例**：注释掉错误代码、使用 `any` 规避类型

## &#127919; 最佳实践

### 1. 增量构建

```bash
# 开发环境（频繁改动）
pnpm run build
# 使用 Turbopack 的增量构建能力
```

### 2. 并行优化

```bash
# 利用多核 CPU
NODE_OPTIONS='--max-old-space-size=4096' pnpm run build
```

### 3. 构建缓存

```json
{
  "scripts": {
    "build": "next build",
    "build:clean": "rm -rf .next && next build",
    "build:analyze": "ANALYZE=true next build"
  }
}
```

## &#128218; 相关文档

- [开发环境规范](../00-开发规范/开发前检查清单.md)
- [部署指南](./部署指南.md)
- [TypeScript 最佳实践](../00-开发规范/前端规范/TypeScript最佳实践.md)

## &#128260; 版本历史

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| 1.0.0 | 2026-02-04 | 初始版本 | Vibe Coding |

---

**重要提示**：本规范为强制执行标准，任何违反行为都必须立即纠正。