Build Error Resolver (建構錯誤修復)

When to Use

在以下情況使用此 Skill：

•npm run build 失敗
•npx tsc --noEmit 顯示錯誤
•類型錯誤阻礙開發
•Import/模組解析錯誤
•設定檔錯誤
•依賴版本衝突

核心原則

•最小化修改 - 只做必要的最小改動
•不重構 - 不改動無關的程式碼
•不改架構 - 只修錯誤，不做設計變更
•快速迭代 - 修一個錯誤，驗證，繼續下一個

診斷指令

bash

# TypeScript 類型檢查 (無輸出)
npx tsc --noEmit

# 顯示所有錯誤
npx tsc --noEmit --pretty --incremental false

# 檢查特定檔案
npx tsc --noEmit path/to/file.ts

# Next.js 建構
npm run build

# ESLint 檢查
npx eslint . --ext .ts,.tsx,.js,.jsx

錯誤修復流程

1. 收集所有錯誤

bash

npx tsc --noEmit --pretty

2. 分類錯誤

•類型推斷失敗
•缺少類型定義
•Import/Export 錯誤
•設定錯誤
•依賴問題

3. 按優先級修復

•阻礙建構：先修
•類型錯誤：依序修
•警告：有時間再修

常見錯誤模式與修復

1. 類型推斷失敗

typescript

// 錯誤: Parameter 'x' implicitly has an 'any' type
function add(x, y) { return x + y }

// 修復: 加上類型註解
function add(x: number, y: number): number { return x + y }

2. Null/Undefined 錯誤

typescript

// 錯誤: Object is possibly 'undefined'
const name = user.name.toUpperCase()

// 修復: Optional chaining
const name = user?.name?.toUpperCase()

// 或: Null check
const name = user && user.name ? user.name.toUpperCase() : ''

3. 缺少屬性

typescript

// 錯誤: Property 'age' does not exist on type 'User'
interface User { name: string }
const user: User = { name: 'John', age: 30 }

// 修復: 新增屬性到 interface
interface User {
  name: string
  age?: number
}

4. Import 錯誤

typescript

// 錯誤: Cannot find module '@/lib/utils'

// 修復 1: 檢查 tsconfig paths
{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

// 修復 2: 使用相對路徑
import { formatDate } from '../lib/utils'

// 修復 3: 安裝缺少的套件
npm install @/lib/utils

5. 類型不符

typescript

// 錯誤: Type 'string' is not assignable to type 'number'
const age: number = "30"

// 修復: 轉型
const age: number = parseInt("30", 10)

6. Generic 限制

typescript

// 錯誤: Type 'T' is not assignable to type 'string'
function getLength<T>(item: T): number {
  return item.length
}

// 修復: 加上限制
function getLength<T extends { length: number }>(item: T): number {
  return item.length
}

7. React Hook 錯誤

typescript

// 錯誤: React Hook cannot be called conditionally
function MyComponent() {
  if (condition) {
    const [state, setState] = useState(0) // 錯誤!
  }
}

// 修復: Hook 移到頂層
function MyComponent() {
  const [state, setState] = useState(0)
  if (!condition) return null
  // 使用 state
}

8. Async/Await 錯誤

typescript

// 錯誤: 'await' only allowed within async functions
function fetchData() {
  const data = await fetch('/api/data')
}

// 修復: 加上 async
async function fetchData() {
  const data = await fetch('/api/data')
}

9. 模組未找到

typescript

// 錯誤: Cannot find module 'react'

// 修復: 安裝依賴
npm install react
npm install --save-dev @types/react

最小化修改策略

做:

•加上缺少的類型註解
•加上必要的 null checks
•修復 imports/exports
•安裝缺少的依賴
•更新類型定義

不做:

•重構無關程式碼
•改變架構
•重新命名變數/函數
•新增功能
•改變邏輯流程
•優化效能

建構錯誤報告格式

markdown

# 建構錯誤修復報告

**日期:** YYYY-MM-DD
**建構目標:** Next.js Production / TypeScript Check
**初始錯誤:** X
**已修復錯誤:** Y
**建構狀態:** 通過 / 失敗

## 已修復錯誤

### 1. [錯誤類別]
**位置:** `src/components/Card.tsx:45`
**錯誤訊息:**
Parameter 'market' implicitly has an 'any' type.

**修復:**
+function formatMarket(market: Market) {
-function formatMarket(market) {

**修改行數:** 1

## 驗證步驟

1. TypeScript 檢查通過: `npx tsc --noEmit`
2. Next.js 建構成功: `npm run build`
3. 無新錯誤產生

錯誤優先級

嚴重 (立即修復)

•建構完全失敗
•開發伺服器無法啟動
•生產部署被阻擋

高 (盡快修復)

•單一檔案失敗
•新程式碼的類型錯誤
•Import 錯誤

中 (有空修復)

•Linter 警告
•已棄用 API 使用
•非嚴格類型問題

快速參考指令

bash

# 檢查錯誤
npx tsc --noEmit

# 清除快取重建
rm -rf .next node_modules/.cache
npm run build

# 安裝缺少的依賴
npm install

# 自動修復 ESLint
npx eslint . --fix

# 驗證 node_modules
rm -rf node_modules package-lock.json
npm install

成功標準

•npx tsc --noEmit 回傳 code 0
•npm run build 成功完成
•無新錯誤產生
•修改行數最小化 (< 受影響檔案的 5%)
•開發伺服器正常運作
•測試仍然通過