开发环境标准

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

> **搜索标签**: 开发环境, 环境配置, 本地环境, 开发配置
---

# 开发环境 vs 构建环境标准

## 核心原则

**所有的开发和修复都必须以构建和生产环境标准为基础**

> "如果代码在构建环境失败，那么在开发环境也应该失败，而不是相反。"

---

## 问题分析

### 错误的开发模式

```
开发环境：
TypeScript 类型错误 → 忽略 → 继续开发
                ↓
                ❌ 错误进入代码库
                ↓
构建环境：
30+ 类型错误 → 构建失败 → &#128295; 紧急修复
```

### 正确的开发模式

```
开发环境：
TypeScript 类型错误 → 立即修复 → 继续开发
                ↓
                ✅ 代码始终保持高质量
                ↓
构建环境：
0 类型错误 → ✅ 构建成功 → &#128640; 可以部署
```

---

## 为什么会积累这么多错误？

### 1. 开发环境配置不严格

```json
// 可能的问题配置
{
  "compilerOptions": {
    "strict": false,              // ❌ 未启用严格模式
    "noUnusedLocals": false,      // ❌ 不检查未使用的变量
    "noUnusedParameters": false,  // ❌ 不检查未使用的参数
    "noImplicitAny": false        // ❌ 允许隐式 any
  }
}
```

**问题：** 开发时看不到类型错误，但构建时检查严格。

### 2. Webpack Dev Server 的容错性

```javascript
// webpack 开发服务器可能：
- 允许一些类型错误运行
- 只在控制台显示警告，不阻止编译
- 使用不同的 babel 配置绕过类型检查
```

**问题：** 开发时能跑，但构建时失败。

### 3. 缺少持续类型检查

```bash
# 应该有，但没有
pnpm type-check    # ❌ 从不运行
pnpm build         # ❌ 只在部署时运行
```

**问题：** 错误在开发时积累，构建时爆发。

### 4. 编辑器配置不严格

```json
// .vscode/settings.json - 可能缺失的配置
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.tsc.autoDetect": "on",  // ✅ 自动检测
  "typescript.preferences.includePackageJsonAutoImports": "auto"
  // 缺少：
  // "typescript.enablePromptUseWorkspaceTsdk": true,
  // "typescript.suggest.autoImports": true
}
```

**问题：** 编辑器中看不到所有类型错误。

---

## 正确的开发环境配置

### 1. TypeScript 配置

```json
// tsconfig.json - 严格配置
{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],

// &#128308; 必须启用严格模式
    "strict": true,

// &#128308; 不跳过类型检查（性能换安全）
    "skipLibCheck": false,

// &#128308; 检查未使用的变量和参数
    "noUnusedLocals": true,
    "noUnusedParameters": true,

// &#128308; 不允许隐式 any
    "noImplicitAny": true,

// &#128308; 检查隐式返回
    "noImplicitReturns": true,

// &#128308; 检查严格的空值检查
    "strictNullChecks": true,

// &#128308; 检查严格属性初始化
    "strictPropertyInitialization": true,

"noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },

"include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts"
  ],

"exclude": [
    "node_modules",
    "drizzle.config.ts",
    "scripts/**"
  ]
}
```

### 2. Webpack 配置

```javascript
// next.config.js - 开发时也进行类型检查
module.exports = {
  webpack: (config) => {
    // 开发模式也运行 TypeScript 检查
    if (process.env.NODE_ENV !== 'production') {
      config.module.rules.push({
        test: /\.(ts|tsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'ts-loader',
          options: {
            transpileOnly: false,  // &#128308; 不跳过类型检查
            happyPackMode: false,
          },
        },
      });
    }
    return config;
  },
};
```

### 3. VSCode 配置

```json
// .vscode/settings.json
{
  // TypeScript 配置
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "typescript.tsc.autoDetect": "on",
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.preferences.includePackageJsonAutoImports": "auto",
  "typescript.suggest.autoImports": true,
  "typescript.suggest.completeFunctionCalls": true,

// &#128308; 启用所有类型检查
  "typescript.tsserver.experimental.enableProjectDiagnostics": true,

// 编辑器配置
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true
  },

"editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",

// &#128308; 显示所有问题
  "problems.showCurrentInStatus": true,
  "problems.sortOrder": "severity"
}
```

### 4. Package.json Scripts

```json
{
  "scripts": {
    // &#128308; 开发前检查
    "pre-dev-check": "pnpm type-check",
    "dev": "pnpm pre-dev-check && pnpm next dev",

// &#128308; 类型检查（必须通过）
    "type-check": "tsc --noEmit",

// &#128308; 详细类型检查
    "type-check:verbose": "tsc --noEmit --pretty false",

// &#128308; 监听模式类型检查
    "type-check:watch": "tsc --noEmit --watch",

// &#128308; 构建检查（必须通过）
    "build": "pnpm type-check && next build",

// &#128308; 启动前检查
    "pre-start": "pnpm type-check",
    "start": "pnpm pre-start && next start",

// &#128308; 提交前检查
    "pre-commit": "pnpm type-check && pnpm lint",

// &#128308; 推送前检查
    "pre-push": "pnpm build",

// &#128308; 只检查特定文件
    "type-check:file": "tsc --noEmit",

// &#128308; 检查所有文件
    "type-check:all": "tsc --noEmit"
  }
}
```

---

## 强制执行机制

### 1. Git Hooks

```bash
# .husky/pre-commit
#!/bin/bash

echo "&#128269; 运行类型检查..."
pnpm type-check || {
  echo ""
  echo "❌ 类型检查失败！"
  echo "请修复类型错误后再提交。"
  echo ""
  echo "运行以下命令查看详细错误："
  echo "  pnpm type-check:verbose"
  exit 1
}

echo "✅ 类型检查通过"
```

```bash
# .husky/pre-push
#!/bin/bash

echo "&#127959;️  运行构建检查..."
pnpm build || {
  echo ""
  echo "❌ 构建失败！"
  echo "请修复错误后再推送。"
  exit 1
}

echo "✅ 构建成功"
```

### 2. CI/CD 配置

```yaml
# .github/workflows/ci.yml
name: CI - 构建环境标准检查

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  # &#128308; 类型检查
  type-check:
    name: 类型检查
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

- name: 安装依赖
        run: pnpm install

- name: 类型检查
        run: pnpm type-check

- name: 详细错误报告
        if: failure()
        run: pnpm type-check:verbose

# &#128308; 构建测试
  build:
    name: 构建测试
    runs-on: ubuntu-latest
    needs: type-check
    steps:
      - uses: actions/checkout@v3

- name: 安装依赖
        run: pnpm install

- name: 构建
        run: pnpm build

- name: 检查构建产物
        run: |
          if [ ! -d ".next" ]; then
            echo "❌ 构建产物不存在"
            exit 1
          fi

# &#128308; ESLint 检查
  lint:
    name: 代码检查
    runs-on: ubuntu-latest
    needs: type-check
    steps:
      - uses: actions/checkout@v3

- name: 安装依赖
        run: pnpm install

- name: ESLint 检查
        run: pnpm lint
```

### 3. Pre-commit 检查脚本

```bash
#!/bin/bash
# scripts/pre-commit-check.sh

set -e  # 遇到错误立即退出

echo "&#128269; 开始提交前检查..."

# 1. 类型检查
echo "&#128221; 检查 TypeScript 类型..."
pnpm type-check || {
  echo ""
  echo "❌ TypeScript 类型检查失败！"
  echo ""
  echo "建议的修复步骤："
  echo "  1. 查看详细错误：pnpm type-check:verbose"
  echo "  2. 修复类型错误"
  echo "  3. 重新检查：pnpm type-check"
  exit 1
}

# 2. ESLint 检查
echo "&#128269; 检查代码风格..."
pnpm lint || {
  echo ""
  echo "❌ ESLint 检查失败！"
  echo ""
  echo "建议的修复步骤："
  echo "  1. 自动修复：pnpm lint --fix"
  echo "  2. 手动修复剩余错误"
  echo "  3. 重新检查：pnpm lint"
  exit 1
}

# 3. 检查是否有未提交的更改
echo "&#128194; 检查未提交的更改..."
if [ -n "$(git diff --cached --name-only | grep -v package-lock.json)" ]; then
  echo "✅ 有文件待提交"
else
  echo "⚠️  没有文件待提交"
fi

echo "✅ 所有检查通过，可以提交"
```

---

## 开发环境 vs 构建环境对比

| 检查项 | 开发环境 | 构建环境 | 一致性 |
|--------|---------|---------|--------|
| TypeScript 类型检查 | ✅ 严格 | ✅ 严格 | ✅ 一致 |
| ESLint | ✅ 运行 | ✅ 运行 | ✅ 一致 |
| 编译错误 | ✅ 阻止 | ✅ 阻止 | ✅ 一致 |
| 警告级别 | ✅ 错误 | ✅ 错误 | ✅ 一致 |
| 严格模式 | ✅ 启用 | ✅ 启用 | ✅ 一致 |

---

## 开发工作流程

### 标准流程

```bash
# 1. 拉取最新代码
git pull

# 2. 运行类型检查
pnpm type-check

# 3. 启动开发服务器（已经做了类型检查）
pnpm dev

# 4. 修改代码
# - 编辑器实时显示类型错误
# - 立即修复看到的错误

# 5. 定期运行类型检查
pnpm type-check

# 6. 提交前检查
pnpm pre-commit

# 7. 提交
git add .
git commit -m "feat: 新功能"

# 8. 推送前检查
pnpm pre-push

# 9. 推送
git push
```

### 错误的流程（我们之前的方式）

```bash
# ❌ 之前的错误流程

# 1. 修改代码
# - 忽略类型错误（红色波浪线）
# - 继续编码

# 2. 提交代码
git add .
git commit -m "fix: 修复"

# 3. 推送
git push

# 4. 部署
# - 构建失败
# - 发现 30+ 类型错误
# - &#128295; 紧急修复
```

---

## 监控和报告

### 1. 类型错误追踪

```bash
# 统计类型错误数量
pnpm type-check 2>&1 | grep -c "error TS"

# 查看详细的类型错误
pnpm type-check:verbose

# 监听模式
pnpm type-check:watch
```

### 2. 构建报告

```bash
# 构建并生成报告
pnpm build --report

# 检查构建产物
ls -lh .next/

# 检查页面生成
ls -lh .next/server/app/
```

### 3. 定期检查

```bash
# 每天早上运行
echo "&#128197; 每日类型检查报告"
pnpm type-check

# 每周五下午运行
echo "&#128202; 周报：类型错误统计"
pnpm type-check:verbose | grep "error TS" | wc -l
```

---

## 快速参考

### 必须的命令

```bash
# &#128308; 开发前
pnpm type-check      # 必须通过

# &#128308; 提交前
pnpm pre-commit      # 必须通过

# &#128308; 推送前
pnpm build           # 必须通过

# &#128308; 部署前
pnpm build           # 必须通过
```

### 常用命令

```bash
# 查看详细错误
pnpm type-check:verbose

# 监听模式
pnpm type-check:watch

# 检查特定文件
tsc --noEmit src/app/page.tsx

# 自动修复 ESLint
pnpm lint --fix
```

---

## 总结

### 核心原则

1. **开发环境 = 构建环境**
   - 开发时就应该看到和构建时一样的错误
   - 不能有"开发时能用"的情况

2. **类型检查强制执行**
   - 开发时、提交前、推送前、部署前都必须检查
   - 任何类型错误都不能进入代码库

3. **持续监控**
   - 定期运行类型检查
   - 监听错误数量
   - 生成错误报告

### 关键机制

- ✅ TypeScript 严格配置
- ✅ Webpack 类型检查
- ✅ VSCode 严格配置
- ✅ Git Hooks 强制检查
- ✅ CI/CD 自动检查
- ✅ Pre-commit 脚本

### 目标

**确保开发环境和构建环境的标准一致，不让任何错误进入生产环境。**

> "如果代码在构建环境失败，那么在开发环境也应该失败。"
>
> "开发环境和构建环境的标准应该完全一致，不允许有任何差异。"