seikaikyo/build-error-resolver

Build Error Resolver (建構錯誤修復)

When to Use

在以下情況使用此 Skill：

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

核心原則

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

診斷指令

# 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. 收集所有錯誤

npx tsc --noEmit --pretty

2. 分類錯誤

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

3. 按優先級修復

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

常見錯誤模式與修復

1. 類型推斷失敗

// 錯誤: 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 錯誤

// 錯誤: 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. 缺少屬性

// 錯誤: 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 錯誤

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

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

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

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

5. 類型不符

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

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

6. Generic 限制

// 錯誤: 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 錯誤

// 錯誤: 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 錯誤

// 錯誤: '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. 模組未找到

// 錯誤: Cannot find module 'react'

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

最小化修改策略

做:

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

不做:

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

建構錯誤報告格式

# 建構錯誤修復報告

**日期:** 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 使用
• 非嚴格類型問題

快速參考指令

# 檢查錯誤
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%)
• 開發伺服器正常運作
• 測試仍然通過