最近在研究 AI Agent 技術，調查 Claude Agent SDK 是否能支援 Human-in-the-loop（人機協作） 以及 不同工作階段的 Agent workflow。

這系列筆記整理了調查過程中的重點，主要參考 Anthropic 官方文件 和實際的 Demo 實作經驗，方便日後查詢。本篇會先介紹 Claude Agent SDK 的基本概念，以及 Human-in-the-loop 在 Agent 系統中的運作方式。

Claude Agent SDK 是什麼？

Claude Agent SDK （前身為 Claude Code SDK）是 Anthropic 官方提供的 SDK，讓開發者在自己的應用程式中嵌入 Claude 的 Agent 能力。

簡單來說，就是把 Claude Code 的能力包成一個函式庫，讓使用者可以在 Web App、API Server 等場景中使用。

SDK vs. Claude Code CLI

這兩者的關係可以這樣理解：

• CLI 是給「人」用的互動工具
• SDK 是給「程式」用的函式庫

如果想在自己的 Web App 或 API 中整合 Agent 功能，SDK 就是你需要的東西。

Agent 的基本組成

在 Claude Agent SDK 中，一個 Agent 通常由三個部分組成：

SDK 的 query() 函式負責協調這三個部分。

AI Agent 的兩個控制層

在實際設計 AI Agent 系統時，通常需要考慮兩個核心問題：

1. Agent 能做什麼？（能力控制）
2. Agent 什麼時候需要人類介入？（決策控制）

在 Claude Agent SDK 中，這兩個層面分別由不同機制負責：

本篇會先介紹第二個部分：Human-in-the-loop 的運作方式。

Human-in-the-loop 人機協作

什麼是 HITL？

Human-in-the-loop（HITL）是指 Agent 在執行過程中，暫停動作、請求人類確認後再繼續的機制。

為什麼需要這個機制呢？因為 Agent 可能會需要執行一些高風險操作（例如刪除檔案、執行系統指令），這時讓人類在關鍵節點上進行審核，可以避免不當操作。

核心機制：canUseTool callback

SDK 提供 一個統一的 callback 來處理所有的人機互動，流程大致如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

User Prompt
   ↓
Claude Agent 推理
   ↓
Agent 想使用 Tool（例如 write_file("config.json")）
   ↓
SDK 呼叫 canUseTool("Write", {...})
   ↓
應用程式決定
  ✓ Allow  → 繼續執行
  ✗ Deny   → 停止這個動作
  ✎ Modify input → 改參數後執行
   ↓
Tool 根據結果執行
   ↓
Agent 繼續推理

重點在於：所有的人機互動都通過這一個 callback，包含工具審核和 Agent 提問，不需要分別處理。

實作程式碼

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

const result = query({
  prompt: "幫我重構這個專案",
  options: {
    canUseTool: async (toolName, input, { signal, decisionReason }) => {
      // 允許執行
      return { behavior: "allow", updatedInput: input };

      // 拒絕執行
      return { behavior: "deny", message: "使用者拒絕了這個操作" };

      // 修改參數後允許
      return { behavior: "allow", updatedInput: { ...input, path: "/safe/path" } };
    },
  },
});

兩種觸發情境

情境 A：工具審核（Tool Approval）

Agent 要使用工具時（如寫入檔案），SDK 自動呼叫 canUseTool 讓人類審核：

1
2
3
4
5
6
7

Agent 想執行 write_file("utils.go")
    ↓
SDK 呼叫 canUseTool("Write", { file_path: "utils.go", ... })
    ↓
應用程式顯示審核 UI → 使用者選擇 Approve / Deny
    ↓
Agent 根據結果繼續或停止

情境 B：AskUserQuestion（Agent 主動提問）

除了工具審核之外，Agent 有時也需要向使用者詢問資訊。

當 Agent 判斷資訊不足時，會呼叫 AskUserQuestion 工具向使用者提問。
這個操作 **同樣會觸發 canUseTool**，但角色不同，此時應用程式需要將問題顯示給使用者，收集答案後再回傳給 Agent。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

canUseTool: async (toolName, input) => {
  if (toolName === "AskUserQuestion") {
    // Agent 在提問 → 顯示問題、收集答案
    const answers = await showQuestionUI(input.questions);
    return {
      behavior: "allow",
      updatedInput: { ...input, answers }
    };
  }

  // 其他工具 → 審核是否允許
  const approved = await showApprovalUI(toolName, input);
  if (approved) {
    return { behavior: "allow", updatedInput: input };
  } else {
    return { behavior: "deny", message: "使用者拒絕" };
  }
}

用一個具體的例子來說明 AskUserQuestion 的流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Agent 不確定要用哪個測試框架
    ↓
Agent 呼叫 AskUserQuestion({
  questions: [{
    question: "你想用哪個測試框架？",
    options: [
      { label: "Jest",   description: "最常用的 JS 測試框架" },
      { label: "Vitest", description: "較新，與 Vite 整合好" }
    ]
  }]
})
    ↓
SDK 呼叫 canUseTool("AskUserQuestion", { questions: [...] })
    ↓
應用程式顯示問題 UI，使用者選了 "Vitest"
    ↓
回傳 { behavior: "allow", updatedInput: { ...input, answers: { "你想用哪個測試框架？": "Vitest" } } }
    ↓
Agent 收到答案，用 Vitest 繼續開發

內建權限策略：permissionMode

permissionMode 是 SDK 內建的預設策略，而 canUseTool 則提供更細緻的控制。這種方式適合快速原型或 CLI 工具，如果需要自訂 UI 或更細緻的控制，通常會搭配 canUseTool 使用。

如果兩者同時存在，SDK 會先套用 permissionMode，再透過 canUseTool 讓應用程式做最終決策。

Claude Agent SDK 在 Web App 中的基本架構

系統架構

在實際的 Web 應用中，Claude Agent SDK 通常會部署在後端 API 層，由前端透過 HTTP 請求與 Agent 互動。

以下是一個典型的 Next.js 架構：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

┌────────────────────────────────────────────┐
│  Next.js Web App                           │
│                                            │
│  ┌──────────┐    POST     ┌─────────────┐  │
│  │ React UI │  ────────→  │ API Route   │  │
│  │ (Chat)   │  ←──SSE───  │ /api/agent  │  │
│  └──────────┘             └──────┬──────┘  │
│                                  │         │
└──────────────────────────────────│─────────┘
                                   │ query()
                            ┌──────▼──────┐
                            │ Claude      │
                            │ Agent SDK   │
                            └──────┬──────┘
                                   │
                            ┌──────▼──────┐
                            │ Claude API  │
                            │ (Anthropic) │
                            └─────────────┘

前端負責顯示聊天 UI 與使用者互動，後端 API Route 則負責呼叫 Claude Agent SDK，並將串流結果回傳給前端。當 Agent 需要人類審核或提問時，則透過 canUseTool callback 觸發應用程式的 UI。

串流回覆與互動流程

實際實作時，Agent 的回覆通常會透過 串流（streaming） 的方式傳回前端，例如使用 SSE（Server-Sent Events）或 WebSocket。

當 canUseTool 觸發需要使用者回覆的情境（例如 AskUserQuestion）時，系統會暫停 Agent 的執行並等待使用者輸入，再繼續推理。

由於 SSE 是單向通信，許多 Web 應用會採用 SSE + REST 的雙通道架構：

• SSE：Server → Client 傳送 Agent 回覆
• REST POST：Client → Server 回傳使用者回答

這種串流與互動的通信設計，涉及較多 Web 架構與 Agent session 管理，本文先聚焦於 Agent SDK 與 Human-in-the-loop 的基本概念，相關實作細節將在後續文章中介紹。

總結

Claude Agent SDK 提供了一個簡單但強大的模型來構建 AI Agent：

• query() 負責執行 Agent 推理流程
• Tools 讓 Agent 可以與外部系統互動
• canUseTool 提供 Human-in-the-loop 機制，讓人類在關鍵操作前介入

透過這些機制，開發者可以在 自動化與人工監督之間取得平衡，建立更安全可控的 AI Agent 系統。

不過在實際的 Web 應用中，為了讓 AI Agent 在自動化與可控性之間取得更好的平衡，還需要進一步設計：

• Agent 回覆的 串流傳輸（SSE / WebSocket）
• AskUserQuestion 等互動流程的 session 管理
• 不同任務階段的 Agent workflow 設計

後續文章將會進一步介紹：

• Agent 串流與互動設計（SSE / WebSocket / REST 架構）
• Agent Workflow 設計（Plan / Execute / Review 模式切換）

參考資料

• Claude Agent SDK 官方文件
• Anthropic API Reference

在定義 Object Types（物件型別）時，兩者寫法看起來幾乎相同，許多情況下還可以互換使用，但它們在設計目的與使用範圍上仍存在一點差異。

本文的結論其實很簡單：

只在 type 做不到的時候，才使用 interface。

這篇文章將從以下幾個角度說明為什麼：

• type 與 interface 的核心差異
• interface 不可取代的場景
• 實務上的使用判斷流程

type 與 interface

在進入正題前，試著判斷以下三題「是否能編譯」，感受 type 和 interface 的差異：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// Q1:
type A = { name: string }
type A = { age: number }            // X:　Duplicate identifier 'A'. (同名報錯)


// Q2:
interface B { name: string }
interface B { age: number }         // O: Declaration Merging (自動合併)


// Q3:
type C = string | number            // O: 定義為 Union 聯合型別

interface D = string | number       // X: interface 只能是物件格式

乍看之下，兩者都是在定義型別，為什麼會出現不同的行為？

以下參考官方原文：

“A type alias is exactly that — a name for any type.”

• type 是 **型別別名（Type Alias）**，用來為任意型別取一個名字

“An interface declaration is another way to name an object type.”

• interface 是 物件型別的另一種命名方式

“The key distinction is that a type cannot be re-opened to add new properties vs an interface which is always extendable.”

• 且 interface 可被重複宣告，用來 擴展屬性（Declaration Merging）

基本語法比較

在最常見的物件型別定義中，兩者寫法幾乎相同：

1
2
3
4
5
6
7
8
9
10
11

// 使用 type
type User = {
  id: string
  name: string
}

// 使用 interface
interface User {
  id: string
  name: string
}

官方原文也指出兩者的相似性：

“Type aliases and interfaces are very similar, and in many cases you can choose between them freely.”

• 在一般物件型別中，兩者通常可以 自由選擇

type 才能做到的事

type 能為任意型別取一個名字，適用範圍比 interface 更廣：

1
2
3
4
5
6
7
8
9
10
11

// Union（聯合型別）
type Status = 'active' | 'inactive'

// Tuple（元組）
type Pair = [string, number]

// Conditional Type（條件型別）
type IsString<T> = T extends string ? true : false

// Mapped Type（映射型別）
type MyReadonly<T> = { readonly [K in keyof T]: T[K] }

官方原文明確說明了 interface 的限制：

“Unlike a type alias, an interface can only describe object shapes; it cannot be used to rename primitives.”

• interface **只能描述物件的形狀**，無法用於定義 Primitive（基本型別）、Union、Tuple 等型別

簡單來說：

• interface → 專門描述「物件結構」
• type → TypeScript 型別系統的通用工具

那麼，什麼情況下必須使用 interface 呢？

interface 不可取代的場景

Declaration Merging 宣告合併

同名的 interface 會被 TypeScript 自動合併：

1
2
3
4

interface Config { debug: boolean }
interface Config { lang: string }

// 結果：Config = { debug: boolean; lang: string }

使用 type 則會直接報錯：

1
2

type Config = { debug: boolean }
type Config = { lang: string }   // ❌ Duplicate identifier

官方原文定義：

“The simplest, and perhaps most common, type of declaration merging is interface merging. At the most basic level, the merge mechanically joins the members of both declarations into a single interface with the same name.”

• Declaration Merging 會將同名 interface 的成員 機械式地結合為單一介面

實務應用：Module Augmentation 擴充第三方型別

Declaration Merging 最重要的實務用途是「擴充第三方套件的型別」，這個做法稱為 Module Augmentation（擴充第三方型別）。

• 使用 interface 擴充型別

1
2
3
4
5
6
7

// ✅ interface → merge 成功
declare module 'react-i18next' {
  interface CustomTypeOptions {
    defaultNS: 'common'
    resources: typeof resources
  }
}

• 使用 type 則會同名報錯

1
2
3
4
5
6

// ❌ type → Duplicate identifier
declare module 'react-i18next' {
  type CustomTypeOptions = {
    defaultNS: 'common'
  }
}

官方原文：

“Although JavaScript modules do not support merging, you can patch existing objects by importing and then updating them.”

• Module Augmentation 透過 Declaration Merging 來 對現有物件進行擴充

class implements 類別契約

• implements 用於檢查類別是否 滿足特定介面的契約

1
2
3
4
5
6
7
8
9

interface Pingable {
  ping(): void
}

class Sonar implements Pingable {
  ping() {
    console.log("ping!")
  }
}

官方原文：

“You can use an implements clause to check that a class satisfies a particular interface. An error will be issued if a class fails to correctly implement it.”

技術上 type 也能搭配 implements 使用，但 interface 更能表達 「這是類別必須遵守的契約」 這層語意，且轉換為 type 沒有實質好處，因此建議維持 interface。

總結

以下整理前面提到的所有差異：

根據使用差異，可以透過以下流程快速判斷：

1
2
3
4
5
6
7
8
9
10
11
12
13

要定義型別
  │
  ▼
在 declare module 內嗎？（Module Augmentation）
  ├─ Yes → 使用 interface（必須）：避免報錯
  │
  ▼
是 class implements 的契約嗎？
  ├─ Yes → 使用 interface（推薦）：語意明確
  │
  ▼
其他所有情況
  └─ 使用 type（預設選擇）：統一風格

在實務開發中，type 與 interface 經常會混合出現在同一個專案中。
當團隊嘗試統一型別定義風格時，才會發現兩者的行為其實並不完全相同。

理解差異後，選擇的標準其實很簡單：

只在 type 做不到的時候，才使用 interface。

這樣既能維持型別工具的一致性，也能在需要擴充型別時保留 interface 的優勢。

補充：interface extends vs type & 的效能差異

TypeScript 官方的 Performance Wiki 中提到：

“Interfaces create a single flat object type that detects property conflicts…
Intersections on the other hand just recursively merge properties, and in some cases produce never.”

簡單來說：

• interface extends 會建立 扁平化（flat）的物件型別
• type A & B（intersection）則會 遞迴地合併型別結構

在複雜型別組合時，intersection 有時需要重新展開計算，甚至可能產生 never。因此 TypeScript 官方建議，在物件型別的繼承或組合場景中，優先使用 interface extends。

不過這個差異通常只會在 大型專案中或複雜型別組合 中才比較明顯，對於一般規模的專案而言，幾乎不會感受到實際影響，因此這裡僅作為補充說明。

延伸閱讀：【結論】TypeScriptの型定義はtypeよりinterfaceを使うべき理由

參考資料

• Everyday Types — Type Aliases
• Everyday Types — Interfaces
• Everyday Types — Differences Between Type Aliases and Interfaces
• TypeScript Cheat Sheets — Interfaces
• Declaration Merging
• Declaration Merging — Module Augmentation
• Classes — implements Clauses

GitHub - https://github.com/shadcn-ui/ui

What is Shadcn UI?

Shadcn UI 是基於 Tailwind CSS 底層封裝 Radix UI 的 React UI 元件集合，能夠支援 Next.js, Astro, Remix, Gatsby 等框架。

shadcn-ui/ui 專案於 2023 年 1 月發布到 GitHub，截至目前（2024 年 7 月）已有超過 65K 星星數，榮登 2023 JavaScript Rising Stars 榜首。

之所以能夠成為炙手可熱的開源專案，如 Shadcn 官方文件介紹所述：

Beautifully designed components that you can copy and paste into your apps. Accessible. Customizable. Open Source.
（您可以複製貼上設計精美的元件至應用程式中。無障礙、可客製化且開源。）

Shadcn UI 並不是一個 component library（元件庫），而是可重用元件的「集合」。換言之，Shadcn UI 並不會以 dependency 的形式出現在 pacakge.json，使用者可以直接把原始碼複製貼上到專案中，也能自行修改客製化。

Why Shadcn UI?

Shadcn UI 在前端生態圈崛起的原因，可從過去我們所熟悉的 UI Framework，如 Bootstrap, Meterial UI, Ant Design 等說起。

透過元件庫提供的預設元件進行開發，就不需要從零開始造輪子，能夠統一介面樣式並實現 RWD 等需求，然而在實際使用元件庫時，會發現在客製化上有一定限制，經常會為了改一小部分樣式，而透過 !important、:deep 等「魔改」的方式，來達到自訂義樣式需求，如此不只增加程式碼的複雜性，也不易後續維護使用。

如上所述，Shadcn UI 具備的種種特性，提供現有的元件庫解決方案，其優點如下：

• 基於 Tailwind CSS 開發：學習曲線相對較低
• 底層封裝 Radix UI：是一種 Headless UI，只包含功能和邏輯、提供完全無樣式、支援無障礙的 UI 元件庫，因此易於客製化
• 可重用的元件集合：官方文件提供許多範例，可根據需求選擇元件、主題樣式，透過 CLI 或手動複製程式碼到專案中編輯使用
• 輕量有彈性：不需一次安裝所有套件，需要時再透過 shadcn-ui 引入使用
• 支援主流框架，如 Next.js, Remix, Vue 等

How to use Shadcn UI?

詳細步驟可參考官方文件，本篇以 Next.js 專案為例：

專案建置 Getting Start

1. 透過 creat-next-app 指令建置 Next.js 專案

1

npx create-next-app@latest my-app --typescript --tailwind --eslint

2. 執行 CLI shadcn-ui 初始專案

1
2

cd my-app
npx shadcn-ui@latest init

3. 選擇系統初始樣式配置，後續也可在設定檔 components.json 做調整

1
2
3

Which style would you like to use? › Default
Which color would you like to use as base color? › Slate
Do you want to use CSS variables for colors? › no / yes

建立好的 Next.js 專案架構可參考如下，其中引入的 Shadcn 元件會放在 compoent/ui 資料夾底下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

.
├── app
│   ├── layout.tsx
│   └── page.tsx
├── components    
│   ├── ui                   // 引入的元件可在專案中進行編輯
│   │   ├── alert-dialog.tsx
│   │   ├── button.tsx
│   │   ├── dropdown-menu.tsx
│   │   └── ...
│   ├── main-nav.tsx         // 將引入的元件進一步客製化元件
│   ├── page-header.tsx
│   ├── alert.tsx
│   ├── sidebar.tsx
│   └── ...
├── lib
│   └── utils.ts
├── styles                   // 自定義樣式
│   └── globals.css
├── next.config.js
├── package.json
├── postcss.config.js
├── tailwind.config.js       // Tailwind 設定檔
└── tsconfig.json

新增字型 Font

1. 引入 font 字型至 root layout

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import type { Metadata } from "next";
import "./globals.css";
import { Inter as FontSans } from "next/font/google"
import { cn } from "@/lib/utils"

const fontSans = FontSans({
  subsets: ["latin"],
  variable: "--font-sans",
})

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={cn(
        "min-h-screen bg-background font-sans antialiased",
        fontSans.variable
      )}>
        {children}
      </body>
    </html>
  );
}

2. 在 tailwind.config.js 調整設定檔 theme.extend.fontFamily，即可根據需求自定義樣式

1
2
3
4
5
6
7
8
9
10
11
12
13
14

const { fontFamily } = require("tailwindcss/defaultTheme")
 
/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ["class"],
  content: ["app/**/*.{ts,tsx}", "components/**/*.{ts,tsx}"],
  theme: {
    extend: {
      fontFamily: {
        sans: ["var(--font-sans)", ...fontFamily.sans],
      },
    },
  },
}

新增按鈕 Button

1. 透過 CLI 安裝 button 元件，或直接從官方文件手動複製

1

npx shadcn-ui@latest add button

安裝好的元件路徑會在 components 底下：@components/ui/button

2. 即可引入專案使用

1
2
3
4
5
6
7
8
9
10
11
12

// app/page.tsx

import { Button } from "@/components/ui/button";

export default function Home() {
  return (
    <>
      <h1>Hello World</h1>
      <Button>Enter!</Button>
    </>
  )
}

3. 除了預設樣式，也可直接編輯元件程式碼，例如在 components/ui/button.tsx 檔案中新增自訂義樣式 newButton，即可在頁面使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// app/page.tsx

import { Button } from "@/components/ui/button";

export default function Home() {
  return (
    <>
      <h1>Hello World</h1>
      <Button variant="outline">outline</Button>
      <Button variant="link">link</Button>
      <Button variant="newButton">newButton</Button>
    </>
  )
}

結果如下：

暗色主題 Dark Mode

由於 Shadcn UI 所有元件已內建 Dark Mode 樣式設定，因此只需搭配 Themes 來實作，而 Next.js 可搭配 next-themes 套件

1. 透過 CLI 安裝 next-themes

1

npm install next-themes

2. 引入 next-themes 中的 ThemeProvider 來管理主題樣式：components/theme-provider.tsx

1
2
3
4
5
6
7
8
9
10
11

// components/theme-provider.tsx

"use client"
 
import * as React from "react"
import { ThemeProvider as NextThemesProvider } from "next-themes"
import { type ThemeProviderProps } from "next-themes/dist/types"
 
export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
  return <NextThemesProvider {...props}>{children}</NextThemesProvider>
}

3. 將 ThemeProvider 引入至 root layout

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// app/layout.tsx

import { ThemeProvider } from "@/components/theme-provider"
 
export default function RootLayout({ children }: RootLayoutProps) {
  return (
    <>
      <html lang="en" suppressHydrationWarning>
        <head />
        <body>
          <ThemeProvider
            attribute="class"
            defaultTheme="system"
            enableSystem
            disableTransitionOnChange
          >
            {children}
          </ThemeProvider>
        </body>
      </html>
    </>
  )
}

4. 建立能觸發切換深淺模式的 ModeToggle 按鈕，這裡可安裝 radix-ui/react-icons 引入 icon 使用

1

npm install @radix-ui/react-icons

5. 新增 toggle button 到頁面，注意需加上 use client 才能引入 useTheme hook 使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

"use client"

import * as React from "react"
import { useTheme } from "next-themes"
import { MoonIcon, SunIcon } from "@radix-ui/react-icons"
import { Button } from "@/components/ui/button";

export default function Home() {
  const { theme, setTheme } = useTheme();

  return (
    <>
      <h1>Hello World</h1>
      <Button variant="outline">outline</Button>
      <Button variant="link">link</Button>
      <Button variant="newButton">newButton</Button>

      <div>
        <Button variant="outline" size="icon" onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
          <SunIcon className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
          <MoonIcon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
          <span className="sr-only">Toggle theme</span>
        </Button>
      </div>
    </>
  )
}

效果如下：

小結

前陣子在開發 Next.js 專案時，是搭配使用 material-ui 這套 UI Framework，卻意外發現在過程中遇到許多痛點：

• MUI 和 Tailwind 樣式需分開設定，可能發生樣式衝突，不易整合管理
• 需注意部分元件為付費方案，如 MUI X Data Grid，免費版的 Data Grid 功能相對較少
• MUI 能達到風格一致性的需求，但元件客製化不易，在開發上較缺乏彈性

因此藉此機會來研究 Shadcn UI，希望能改善開發上遇到的問題，後續再根據專案需求來導入合適的方案，畢竟任何工具沒有絕對好壞，而是根據使用情境來評估是否導入使用。

Reference

• 為什麼 Shadcn UI 是 2023 年前端最熱門的開源專案？
• Shadcn-ui : 美觀、無障礙、又能 100 % 客製化的「元件合集」
• 在 2023 年屌爆了一整年的 shadcn/ui 用的 Headless UI 到底是何方神圣？

這篇主要用來記錄 Next.js 開發過程採的坑，後續也會不定期更新：

• 問題一：如何修復 "Window is not defined" error
• 問題二：在 use client 頁面實作動態路由顯示 missing generateStaticParams() error

問題一：如何修復 “Window is not defined” error in Next.js

事情發生在開發 Next.js APP，要實作 Google 登入驗證，需要使用 Window、Document 物件時，發現程式會報出以下錯誤：

1
2
3
4
5

ReferenceError: window is not defined

or

ReferenceError: document is not defined

發生原因

這是由於 Next.js 預設為伺服器渲染（Server-side Rendering），會在 Node.js 環境下預渲染頁面，並將生成的 HTML 內容發送給 Client 端。

因此渲染過程是在 Server 端而非在瀏覽器中，由於程式無法識別 Window / Document 物件而回報上述 Error。

如何解決？

解決方法可透過條件渲染（Conditional Rendering），確保 Next.js 只在 Client 端執行指定的程式碼，

可透過以下兩種方式來實現：

• 檢查 window 是否存在
• 使用 useEffect hook

(1) 檢查 window 是否存在

判斷 window 是否存在，確定在瀏覽器中才執行指定的程式碼：

1
2
3
4
5
6

const isBrowser = () => typeof window !== 'undefined';

if (typeof window !== 'undefined') {
    // Client-side-only
    console.log('window: ', window);
};

(2) 使用 useEffect 等 Hooks

透過 useEffect 等方法，可確保程式碼只會在 Client 端執行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

'use client';
import React, { useEffect } from 'react';

// ...

useEffect(() => {
    // Client-side-only        
    console.log('window: ', window);
    
    window.addEventListener('scroll', (e) => {
    console.log('srcoll: ', e)
  })
},[])

參考資料

• Window is not defined in Next.js React app
• 如何修复Next.js中的 “window is not defined”？ - 掘金

問題二：在 use client 頁面實作動態路由顯示 missing generateStaticParams() error

事情發生在開發 Next.js APP，實作 dynamic routing 時（如：server/[evo]/page.tsx），會顯示以下錯誤：

上述錯誤訊息中的"output: export"，是 Next.js 提供支援 Static Exports（靜態導出），透過在設定檔 next.config.js 加上參數：

1
2
3
4
5

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Outputs a Single-Page Application (SPA)

export default nextConfig

如此一來，即可在 next build 建置時實現 SPA （single-page application），將會在 out 資料夾底下生成靜態檔案，將每個路由分解為單獨的 HTML 檔案，避免在 Client 端載入不必要的 JS 程式碼，減少 bundle 大小以提高頁面效能。

發生原因

但在 Next.js 若想要實現 Dynamic Routes（動態路由），必須加上 generateStaticParams() 方法，這段 function 只能在 Server Component 執行，在 Client Component 並不支援。

官方文件（Deploying: Static Exports | Next.js） 也提到 App Routing 若想要 Dynamic Routes 必須搭配「只能在 SSR 運行的 generateStaticParams()」：

如何解決？

如果想要輸出 SPA，又希望能在 'use client' 情境中實現動態路由，則需要將元件拆成兩個部分實作：

• 在 Server Component 引入 generateStaticParams() 方法，以實現動態路由
• 接著引入 Client Component，即可使用 Hooks

以下是範例程式碼，詳細可參考這篇文章《usage of generateStaticParams with use client | by Vivi - Medium》

• server/[evo]/page.tsx：在 Server Component 引入 generateStaticParams() 方法，以實現動態路由

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// server/[evo]/page.tsx

import EvoPage, { Props } from ".";

export function generateStaticParams() {
  return [
    { evo: 'test' },
    { evo: 'stage' },
    { evo: 'public' }
  ];
}

export default function ServerEvoPage({ params }: Props) {
  console.log('[ServerEvoPage] params', params)
  return <EvoPage params={{ evo: params.evo }}/>;
}

• server/[evo]/index.tsx：在上述 Server Component 引入 Client Component，即可使用 Hooks：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// server/[evo]/index.tsx

'use client';
import React from 'react';

export type Props = {
  params: { evo: string};
};

export default function EvoPage({ params }: Props) {
  console.log('[EvoPage] params: ', params);
  const [data, setData] = React.useState('');
    
  return (
    <div>
        This is Client Component.
    </div>
  );
}

參考資料

• [NEXT-1049] use client with generateStaticParams will opt out of static generation #46735
• [NEXT-1030] output: ‘export’ with use client in dynamic routes doesn’t work #48022
• App Router with output: export does not support useParams() on client #54393
• NextJs-静态导出
• Day 19 - Next.js 13 App Router 動態路由 Dynamic Routes & getStaticParams()

Ref: Next.js - Parallel Routes

前言

接續上篇文章 【學習筆記】談談 Next.js：基於 React 的 SSR 框架，初步瞭解 Next.js 這套框架的特性以及網頁渲染方式，本篇將實際建立 Next.js 專案，以及介紹 Page Router 與 APP Router 兩種路由系統的差異。

Getting Started

詳細步驟可參考官方文件，注意目前版本的 Next.js v14 需要安裝 Node.js v18.17 或以上版本才支援。

nvm：Node Version Manager

若已經安裝過 Node.js 卻顯示版本不符，可透過 nvm 這項 Node.js 版本管理工具，在不同專案中切換 Node.js 版本。

首先在終端機輸入下方指令安裝 nvm：

1

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

接著透過下方指令，即可安裝與套用指定版本的 Node.js：

1
2
3
4
5

$ nvm install v18.17.0
// 安裝指定版本 Node.js
 
$ nvm use v18.17.0
// 套用指定版本的 Node.js

也可透過以下指定確認目前版本，以及已安裝的版本：

1
2
3
4
5
6
7
8

$ node -v
// 確認目前 Node.js 版本

$ nvm ls
// 列出所有本機端已安裝的 Node.js 版本

$ nvm ls-remote
// 列出目前遠端可使用的 Node.js 版本

專案建置

依照下方指令建立 next 專案，在後方加上 --ts 或 --typescript 即可支援 TypeScript 語法：

1
2
3

$ npx create-next-app
or
$ npx create-next-app --ts

接著會依序出現下列幾個提問，分別如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

What is your project named? my-app
// 專案名稱，格式需為英文小寫

Would you like to use TypeScript? No / Yes
// 是否支援 TypeScript

Would you like to use ESLint? No / Yes
// 是否使用 ESLint（用來規範 Coding Style 的套件）

Would you like to use Tailwind CSS? No / Yes
// 是否使用 Tailwind CSS

Would you like to use `src/` directory? No / Yes
// 是否在 /app 外加一層 src 資料夾

Would you like to use App Router? (recommended) No / Yes
// 是否使用 App Router 

Would you like to customize the default import alias (@/*)? No / Yes
// 是否自訂 alias 調整預設的 baseURL 匯入路徑

What import alias would you like configured? @/*
// alias 預設使用 @ 是否修改

建置完成後，初始專案架構主要分成以下三大類：

• app：放置 components、pages 與 api 等檔案
  • layout.tsx：在多個頁面之間定義共用 UI，其狀態將會被保存，如：nav、header、footer 等元件
  • page.tsx：在資料夾底下需包含 page.tsx 檔案，才會被定義為一個 route segment，如：app/blog/page.tsx
  • globals.css：定義全域樣式
• public：放置靜態檔案，如圖片等
  • 需要引入 /public/next.svg 檔案時，路徑可直接指向 /next.svg
• 設定檔：包含 next.config.js、tsconfig.json、package.json 等用於設定專案配置的檔案

接著輸入 cd my-app 指令移動到專案根目錄，再以 npm run dev 指令運行開發伺服器，進入 http://localhost:3000/ 即可看到初始頁面如下，也就是 app/page.tsx 的內容：

Router System 路由系統

過去我們在 React 專案中，曾使用 react-router-dom 這項套件來實現路由功能，詳細可參考這篇筆記：[week 22] React：用 SPA 架構實作一個部落格（一）- Router。

由於 Next.js 使用基於檔案系統的路由（file-system based router），會依照專案的檔案結構自動定義路由。

而根據版本不同，Next.js 提供兩種管理頁面路由的方式，分別是舊版本適用的 Pages Router 以及 v13 後推出的 App Router，兩者差異在於：

• Pages Router
  • 定義頁面層級的路由
  • 所有元件為 React Client Component（客戶端元件）
  • 只能使用 Next.js 提供的預設規則，如：檔案名稱即為路徑
• App Router
  • 定義應用程式層級的路由
  • 所有元件預設為 React Server Component（伺服器端元件）
  • 可自定義路由規則，如：使用正則表達式匹配特定路徑

如上所言，在 App Router 中所有元件預設為 React Server Component（RSC），意思是由伺服器將 React Component 準備好，再傳給 Client 顯示在畫面上。

而 RSC 的優缺點如下：

• 優點
  • 整合後端操作，如存取資料庫（DB）、讀取檔案（File System）
  • 降低資料間的依賴關係，改善請求瀑布流（Waterfall）導致的效能問題
  • 降低 JS Bundle Size 以提升頁面效能
• 缺點
  • 無法使用 React Hooks
  • 無法使用瀏覽器 API
  • 無法操作 DOM 事件監聽

面對上述缺點，Next.js 可依照使用情境不同，將元件定義為 Server Component 或 Client Component。舉例來說，當某個元件需要使用 Hooks 管理時，可透過在程式碼開頭加上 'use client' 來標示元件類型，該元件底下的子元件也會自動視為 Client Component。

但也因為如此，相較於 Page Router，新版的 App Router 學習曲線會較高，需瞭解 Server 如何運作，以及判斷哪些元件適合放在 Server 或 Client 端，在使用時須特別注意。

介紹完 Page Router 和 App Router 之間的差異，接著談談兩者專案架構，以及對應路由的方式。

Page Router：基於檔案的路由系統

檔案架構示意：

1
2
3
4
5
6
7
8
9
10

└── pages
    ├── index.tsx
    ├── login.tsx
    ├── api
    │   └── user.tsx
    ├── posts
    │   └── [id].tsx
    └── blog
        ├── index.tsx
        └── setting.tsx

檔案與對應的頁面路由如下：

• pages/index.tsx → /
• pages/blog/index.tsx → /blog
• pages/blog/setting.tsx → /blog/setting
• pages/posts/[id].tsx → /posts/[id]
  • 檔名可作為動態路由的參數，透過 useRoute 這個 Hook 取得 route 相關資訊
• 呼叫 API：page/api/user.tsx

可參考官方部落格的這篇文章《Layouts RFC》，包含以下檔案對應頁面路由的示意圖：

App Router：基於目錄的路由系統

目錄架構示意：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

└── app
    ├── blog
    │   └── [slug]
    │        └── page.tsx
    ├── login
    │   └── page.tsx
    ├── @analytics
    │   ├── page.tsx
    │   ├── error.tsx
    │   └── loading.tsx
    ├── api
    │   └── user
    │       ├── index.ts
    │       └── route.ts  
    ├── components
    │   ├── loading.tsx
    │   └── button.tsx    
    ├── globals.css
    ├── layout.tsx
    └── page.tsx

文件目錄與對應的頁面路由如下：

• app/page.tsx → /
• app/login/page.tsx → /login
• app/blog/[slug]/page.tsx → /blog/[slug]
  • 目錄可作為動態路由的參數，並以 props 傳入元件
• 呼叫 API：app/api/user/route.tsx
• @ 開頭的 folder 不會對路由造成影響：
  • app/@analytics/page.tsx 實際渲染的路由為 /，這個特殊的檔案夾是用來切分同一個路由底下的不同邏輯區塊。

可參考官方文件，以下是目錄對應頁面路由的示意圖：

File Convention 檔案規則

詳細的路由架構，可參考官方文件，也可以直接在頁面左上方切換查看 App Router 或 Page Router。

此外，Next.js 有設定保留字給特殊檔案，以建立具有特定行為的 UI，以下副檔名為 .js、.jsx、.tsx 可視專案而定：

• layout.js：定義共用 UI 元件
• template.js：類似 layout，處理需要重新渲染的 Layout UI
• page.js：建立路由的主要 UI，並使路徑可公開存取
• route.js：建立伺服器端 API 端點
• loading.js：在載入時顯示載入中 UI
• not-found.js：處理 notFound error（HTTP 404）或任何未知路徑錯誤
• error.js：顯示錯誤 UI，必須為 Client Components
• global-error.js：全域錯誤 UI
• default.js：處理 Parallel Routes（平行路由） 遇到渲染問題時，用來替代顯示的 UI（fallback UI）

以下是官方文件提供的路由範例架構，可以看到父層和子層均有 layout、error 以及 loading 元件，用來處理各自的邏輯：

結語

在查路由相關的資料時，會發現因為 App Router 是 Next.js v13 後才推出的路由系統，架構上和 Page Router 不相容，規則也有所差異，因此特別列出來進行比較，實際開發時使用預設的 App Router 即可。

接下來預計會實作一個的部落格，希望包含簡易的登入機制、API 串接、顯示文章列表等功能。

參考資料

• Next.js 官方文件：App Router & Page Router
• 快速入門 Next.Js 13 App Router, RSC(React Server Component), SEO相關說明
• Day 19 - Parallel Routes 路由的平行宇宙 - iT 邦幫忙

前言

在認識 Next.js 之前，建議先複習 React 的相關知識，可參考過去的《[week 21] 初探 React：Component、JSX 語法、props 與 state 的不同》系列筆記。

距離上次碰 React 感覺已經是好久以前的事情了，趁著這次組內專案需求，預計導入 Next.js 框架技術，寫下這篇學習筆記做記錄。

初探 Next.js

React vs Next.js：函式庫與框架

眾所周知，React 其實並不是框架（Framework），而是用來建構使用者介面的 JavaScript 函式庫（Library）。

而 Next.js 則是建立 React 之上的框架，除了客戶端渲染（Client-side Rendering），還支援兩種形式的預渲染：靜態網頁生成（Static Site Generation）和伺服器端渲染（Server-side Rendering）。

可參考官網的標語介紹：

• React：用於打造使用者介面的函式庫（The library for web and native user interfaces）
  • 此外官方也提到：「建議使用者使用全端 React 框架，如 Next.js 或 Remix，以處理專案中的路由與資料處理等需求」
• Next.js：用於網頁開發的 React 框架（The React Framework for the Web）

為何選擇 Next.js？

在使用任何新技術之前，都要先問為什麼會做出這個選擇，是否有解決實作上面臨的問題 （畢竟面試也很常會被問到），先瞭解前因後果，也有助於掌握各種工具的使用時機。

這裡我們可以從 React 提供的功能作為切入點，React 是由 Facebook 團隊所維護的 JavaScript 函式庫。

Angular、React、Vue，也就是俗稱的前端三大「框架」，常用於快速開發單頁式應用程式（Single Page Application，SPA），可達到前後端分離，以及提升使用者體驗等目的，例如 Gmail、Facebook 和 Netflix 等平台。

然而，由於 SPA 是利用客戶端渲染（CSR）技術，由 JavaScript 動態產生內容，若檢視原始碼會發現無法看到新增的內容，這將導致 SEO（搜尋引擎最佳化）較差的問題；也因為初次載入頁面需下載大量的 JavaScript 檔案，使第一次渲染較為費時，反而降低使用者體驗。

那該怎麼辦呢？

只要第一個畫面改由伺服器端渲染（SSR），即可解決 SEO 問題，其他畫面仍維持使用者端渲染（CSR），減少伺服器運算負荷，如此不就能夠兩者兼得了嗎？

React 可透過「搭建後端 Server + 處理 Hydration + Webpack 打包配置」等設定來實現 SSR，但相對來說門檻較高，需耗費較多成本學習。

於是前端 SSR 框架就誕生了，如 React 的 Next.js 和 Gatsby.js，以及 Vue 的 Nuxt.js。

【延伸閱讀】關於 MVC、SPA 到 SSR 詳細演進，可閱讀 Huli 寫的這兩篇文章：《跟著小明一起搞懂技術名詞：MVC、SPA 與SSR》以及《從歷史的角度探討多種 SSR（Server-side rendering）》，前者明明是兩年前才讀過的文章，現在又有一層新的體悟。

Next.js 特別在哪？

由 Vercel 團隊創建的 Next.js，解決了上述幾點網頁開發遇到的問題，以下是官網提及有關 Next.js v14（發布於 2023 年 12 月）的幾項特點：

• Data Fetching：可控制資料載入的時機點
• CSS Support：內建支援 CSS、Sass 檔案，並支援 CSS 模組化
• Route Handlers：基於檔案架構的路由系統，如 page/home.tsx
• API Routes：支援 API 路由，易於建立與管理 API 端點
• Pre-rendering：支援兩種形式的預渲染，分別是靜態網頁生成（SSG）和伺服器渲染（SSR）
• Built-in Optimizations：針對圖片、字體、JavaScript 載入進行自動優化，包括延遲載入與緩存處理

綜合上述優點，Next.js 有助於優化網頁效能與 SEO，適合用於建立著陸頁面（Landing Page）或是產品展示頁面，但較不適合應用在經常變動的網站，避免伺服器負荷過大。

而 Next.js 實際使用案例可參考 Showcase 頁面，如 Notion、Tik Tok 以及 Twitch 等網站。

比較：CSR vs SSR vs SSG vs ISR

Ref: Next.js: The Ultimate Cheat Sheet To Page Rendering

最後針對 Next.js 支援的網頁渲染方式，以及如何在 Next.js 搭配使用，列點整理如下：

• Client-side Rendering（CSR）：客戶端渲染
  • Client（瀏覽器）第一次發送 Request 給 Server => Server 回傳只有容器不含內容的 HTML 檔 => 再由瀏覽器執行 JavaScript 動態產生資料 => 最後將資料渲染到畫面上
  • 因此第一次渲染較為費時，而只有容器沒有內容的原始碼也將不利於 SEO
  • 執行函數：useEffect() 或使用由 Next.js 團隊開發的 SWR 開源
    套件
• Server-side Rendering（SSR）：伺服器端渲染
  • Server（伺服器）在每次收到 Request 時，會建立好完整的 HTML 內容並發送給 Client
  • 適用於需經常更新數據的頁面，缺點是可能導致伺服器負荷較大
  • 執行函數：getServerSideProps()，只會在 Server side 執行，可跳過呼叫 API 步驟直接到資料庫抓取資料
• Static Site Generation（SSG）：靜態網站生成
  • 在網頁打包（built time）時，就由 Server 產生所有需要用到的內容，因此每次 Server 收到 Request 均回傳相同的 HTML 給 Client
  • 因 HTML 內容不變可搭配快取機制，適用於資料變動較小的頁面，無法動態更新
  • 執行函數：getStaticProps()
• Incremental Site Rendering（ISR）：增量式網站渲染
  • 結合 SSG 和 SSR 的渲染方式，可設定條件保存上一次渲染結果，當靜態檔案過期，將觸發 Server 重新 build HTML 檔案以更新頁面
  • 執行函數: getStaticProps() 搭配 revalidate 屬性

也可參考 web.dev 這篇文章《Rendering on the Web》 提供的表格整理：

結語

在實際瞭解 Next.js 這套框架之前，在社群或其他平台略有耳聞，透過這次學習，除了把 React 的基礎，也把過去常被問到的 MVC、SPA、CSR、SSR 等專有名詞再重新複習一遍。

不管選擇什麼技術或框架，重要的是為何要使用，又想解決什麼問題，不外乎結果都是為了提升使用者體驗，畢竟科技始終源自於人性。這篇只提及基本觀念，再來就是實際動手操作啦！

參考資料

• 18. [FE] 為什麼網站要做成SPA？SSR 的優點是什麼？
• 深入淺出，完整認識Next.js 13 - iT 邦幫忙
• 快速了解Next.js中的網頁渲染技術重點: SSR、SSG、ISR與CSR

• 翻譯流程
• 文章管理
• 輔助翻譯工具
• 其他選擇
• iThome 平台使用心得
• 結語

翻譯流程

簡單記述這次在翻譯文章時的流程，步驟大致如下：

• 在 Qiita 篩選感興趣的文章
• 使用 Notion 管理日文初稿
• 搭配 ChatGPT 等工具進行翻譯
• 翻譯完成後，會再轉移到 HackMD 管理，主要是確認 Markdown 語法是否有問題
• 貼到 iThome 編輯器，進行最後確認，沒問題就儲存成草稿
• 隔天起床發文送出

關於文章篩選，除了是挑自己感興趣且討論度高的主題以外，也會盡量挑選文章字數在 3 千字上下，感覺翻譯起來比較不會有負擔，但凡事總是有例外，還是有幾篇字數突破到 5 千字以上，卻又無法輕易割捨⋯⋯

在正式開賽前，庫存約有十篇翻譯，到第十天左右進度也很有餘裕，因此天真地以為肯定能夠提早完成，舒舒服服迎接完賽。

隨著時間進行到中期，開始進入到偏技術性的文章，就不能單純仰賴翻譯工具進行翻譯，而是時常需要 Google 或查看 Wiki 等確保用字，以避免自創新詞的情況發生。甚至途中還發生點小插曲，雖然已經完成整篇翻譯，自己卻覺得主題有點太淺，結果乾脆當作練習，另外再找篇新的文章。

結果可想而知，到了後期，進度急速被壓縮，幾乎變成一兩天內就要完成一篇翻譯。也因此，真的還是需要提前把文章準備好，才不會整天被死線追著跑Orz

最後挑選主題，依照類別如下所示，這系列文章也已經整理到個人部落格：

• 非程式語言
  • 入門篇(9)
  • 豆知識篇(6)
  • 職涯篇(4)
  • 工具篇(4)
• 程式語言
  • 前端技術篇(4)
  • 後端技術篇(2)
  • 雲端篇(1)

其實選文結果跟自己原本預想差蠻多的，因為一開始的想法，是希望能夠程式與非程式各佔一半，程式語言的部分，理想是能夠介紹到四五種語言。

但現實是骨感的，想要能夠在一篇文章中清楚介紹一門程式語言，其實不是件容易的事。如果想要深入探討，這類型文章通常篇幅較長；如果篇幅較短，又可能會是比較粗淺的入門介紹。也因此，最後還是選擇非技術語言類別的文章居多。

文章管理

平時在做筆記的時候，也會像這樣搭配 Notion 與 HackMD 來管理文章。以前的我，其實是忠實的 HackMD 粉，但自從瞭解到 Notion 強大的資料管理功能，漸漸轉變成雙棲用戶。之所以仍無法捨棄 HackMD，是因為作為 Markdown 檔案編輯器，使用體驗還是很棒，但對於分類管理就不是強項，這點就靠 Notion 來進行互補。

總結兩者的優缺點如下：

• Notion

  • 強大的資料管理功能

  • 可以直接內嵌圖片、影片和連結

  • 不需花太多心思，就能讓畫面賞心悅目

  • 因為功能眾多，一開始可能需要點時間熟悉使用方法

  • 雖然支援 Markdown 語法，但匯出檔案有時符號會出現在奇怪位置

    

• HackMD
  • 支援 Markdown 語法
  • 編輯器能使用雙欄位模式，編輯的同時馬上顯示預覽結果
  • 能夠直接插入圖片並生成語法
  • 能夠與 GitHub 同步筆記，進行文章備份
  • 文章管理較弱，僅能夠以「標籤」進行文章分類

輔助翻譯工具

現在的翻譯工具，已經比起過去充滿「機翻味」的 Google 翻譯成熟許多，尤其是在初次見識到 ChatGPT 的翻譯功能，更是令人嘆為觀止。

一如寫程式能夠直接問 ChatGPT，翻譯也能夠輕易達成。雖然遇到較複雜的情境，或是文法斷句較不規則的情況，還是很容易出現奇怪的結果，甚至翻譯出完全相反的語意。因此，想要完全取代人力可能還為之過早，但不可置否，若能夠妥善使用這些工具，將能夠大幅提升工作效率。或許機器能夠達到 80% 的要求，剩下更細微的部分，就需要由人力去進行優化。

除了 ChatGPT，主要還使用以下幾種翻譯工具：

ChatGPT

• 網頁版：https://chat.openai.com/
• Chrome 擴充功能：**ChatGPT for Google**
  • 個人認為比 ChatGPT 官網好用，使用上穩定很多，不會經常出現錯誤導致對話卡住
• 使用免費版 GPT-3.5

Bing Chat

• 網頁版：https://www.bing.com/search?q=Bing+AI&showconv=1&FORM=hpcodx
• 支援 GPT-4，就翻譯而言沒有太大差別，但或許對寫程式仍有一定幫助
• 次數限制這點真的不太友善，如果不是遇到特別複雜的結構，可能不太會想用 Bing 來協助翻譯
• 詳細可參考這篇：Day24 - 啊？你還在用 ChatGPT 嗎？ Bing 可以免費使用 GPT-4 喔！

DeepL Translate

• 網頁版：https://www.deepl.com/zh/translator/l/en/zh
• Chrome 擴充功能：DeepL Translate: Reading & writing translator
• 中文只有簡體，尚未支援繁體
  • 雖然可搭配「簡轉繁中」的工具，但多一步驟就是有點麻煩

Mate Translate

• Chrome 擴充功能：Mate Translate – translator, dictionary
• 在閱讀文章時，無意間發現這項工具，體驗上比只有簡體的 DeepL 優秀很多
• 用法同樣是選取翻譯區塊，旁邊會出現 icon 可點選進行翻譯，或是點選右上角的 icon 進行全頁翻譯

使用畫面如下所示，選取區塊旁的兩個 icon 分別是 DeepL 和 Mate：

然而，以上這些翻譯工具，即使輸入提示文字「請翻譯成繁體中文」或下一些「限制語句」，偶爾還是會冒出對岸用語或簡體中文。

舉出部分例子作為對照，如下表所示，這點在翻譯時需特別注意：

其他選擇

除了文章編輯管理工具，以及輔助翻譯工具以外，也會搭配以下方式：

goo 辭書

• 日語辭典
• 遇到一些即使 Google 還是不懂意思，或甚至找不到中文翻譯，直接翻日語詞典也是個辦法
• 遇到較口語或新潮的用語，還是要善用 Google 搜尋
  • 如何提升 Google 搜尋能力，可參考這篇：Day3 - 工程師必備技能——Google 之力

教育部重編國語辭典

• 沒錯！就是中文辭典
• 避免口語化，確保不是使用台語或對岸用語
  • 例如：來去～、觀看視頻
• 有時翻譯奧妙的點就在於，發現自己明明懂日文意思，卻不知道該如何用中文表達 （或突然覺得自己不會中文） 的時候，避免出現奇怪自創用詞

問問強者朋友

• 不懂就問！問問精通日文的親朋好友，或是在 PTT、HiNative 等平台發問
• 此外，「翻譯時開著教育部辭典和日文辭典，只要有疑慮就查」這點，就是詢問有在接案翻譯的朋友得到的建議

iThome 平台使用心得

接下來，雖然跟主題比較無關，但這次藉由鐵人賽的機會，第一次使用 iThome 平台發文，在過程中對文章編輯器有些感想：

1. 不能一次上傳多張圖片，只能一張一張分開傳
   • 解決方法：先上傳到 HackMD 或 Imgur 等圖片空間，調整語法後再貼過來
2. 不支援內嵌影片語法，只能用編輯器的內建功能插入影片
3. 無法用 markdown 語法控制圖片大小，如以下範例：
   • ![](https://sample.png =300x450)
   • <img src="https://sample.png" width=“300”>
4. 文章部分沒有內建目錄系統，也不支援 [TOC]（Table Of Contents） 這類能夠建立目錄的語法

雖然在編輯器頁面中，就有顯示「不支援部分 HTML 內容」的標語，並舉出可使用的 Markdown 常用語法，但還是感覺使用上稍微不方便就是：

結語

轉職成為前端工程師以來，終於輪到自己參賽，從閱讀者的角色轉變為創作者，感覺還是很不可思議。

先前也有在文章中提到，原本自己是想要以 AWS 為主題參賽的。起因是，一直在思考今年能不能有什麼突破，從年中就有計畫要考取 AWS 證照，卻遲遲沒辦法有可見的進度，甚至陷入一段小小低潮。

雖然是題外話，原本其實有過想去日本留學的夢想，甚至還在今年申請到別科資格，雖然後來因為職涯考量還是放棄了。仔細想了想，其實自己已經具備基礎的日文能力，畢竟打從一開始，就是以「興趣」驅動學習日文這件事，那麼何不以這為切入點，試試看能不能借此點燃學習程式的熱情呢？於是就開啟了這次鐵人賽的旅程。

最後，儘管說是創作，但翻譯本身仍舊是建立在他人的「成果」上，透過這次大量閱讀技術文章，除了瞭解與技術、軟硬實力與學習相關的知識內容，同時也瞭解文章架構，以及敘事方式。期許明年或是未來的自己，能夠真正「創作」文章進行技術分享。

感謝您的閱讀，如果發現文章內容有誤或有什麼建議，歡迎留言告訴我，我們有緣再相見！

15th鐵人賽目錄傳送門：https://ithelp.ithome.com.tw/users/20135558/ironman/6290

原文連結：技術に興味がなくて何が悪い？ - Qiita

最後選擇這篇文章作為結尾，是自己也覺得挺有意思的主題。

作者從自身角度，說明為何不贊同「對技術不感興趣的人不適合成為工程師」這項論點；再進一步透過自身經歷，分享即使對技術不感興趣，該如何以工程師的身份面對工作。

畢竟自己對於技術本身，可能也稱不上是「充滿興趣」的那一側人種，但不可否認的是，學習也好，工作也罷，若能從中獲得成就感，仍舊是讓人樂此不疲的事情。

那麼，以下正文開始！

TL;DR

即使對技術不感興趣，也可以成為一名工程師。

【註】TL:DR = Too Long; Didn’t Read.（長話短說、簡言之）

目標讀者

認為自己對技術不感興趣的人

關於筆者

• Web 應用程式開發工程師，主要工作包括程式細部設計、畫面設計和編碼。
• 對技術不太感興趣。

前言

在工程師的圈子，經常可以看到以下類似的主張：

• 應該在假日學習。
• 應該經常關注最新的技術趨勢。
• 應該參加技術活動。
• 應該每天寫程式。
• 應該學習現代技術，而不是過時的技術。

etc…

而當這些「應該論」變得更加強烈時，甚至會出現「對技術不感興趣的人不適合當工程師」這樣的言論，並且有不少人贊同這種觀點。

前陣子，我在某個社群（SNS）看到以下對話：

新手工程師的提問
我應該在假日學習嗎？

現役工程師的回答
提出這種問題說明你不適合做工程師，還是辭職吧。

接下來撰寫的內容，即使是對技術不感興趣的新手工程師，也完全沒有問題。我自己也是如此，很高興從事工程師的工作。不論是因為「可以賺錢」、「想要遠端工作」或是「IT 領域感覺很熱門」，基於這些動機而成為一名工程師。但為了生存，仍必須學習必要的知識。

我認為，即使對技術不感興趣，也不代表不適合成為工程師。對技術是否感興趣，和是否適合工程師這個職業不一定相符。我自己對技術並不太感興趣，但我認為自己非常適合工程師這個職業。
因此，我決定撰寫這篇文章，重新整理關於 「工程師和對技術的興趣」 的想法，希望能夠給那些因為對技術缺乏興趣而感到壓力的工程師，或那些正在考慮成為工程師的人一點鼓勵。

「對技術不感興趣的人不適合成為工程師」的根據

首先，「對技術不感興趣的人不適合成為工程師」這種主張，可能是從什麼樣的思維中產生的？我認為以下是根本原因：

工程師需要持續學習技術，如果沒有興趣將難以做到。

然而，我認為事情並非如此。

是否需要持續學習技術

這在某種程度上是真實的。因為技術的進化和變遷非常劇烈，而且變化的速度似乎每年都在加快。
雖然計算機科學的基礎技術不會經常改變，但實際在工作現場需要掌握的技術，例如程式語言或 AWS/GCP/Azure 等雲端服務，可以說變化非常快速。

然而，一旦掌握了現場所需的技術，不太可能會因為日後不再持續學習，而失去工程師的職位。

這可能是一個極端的例子，但即使是動態語言從這個世界上消失，Ruby 或 PHP 的工程師是否會突然失業呢？我認為不會，既然擁有現場等級的技術能力，適應靜態語言可能也不需要花太多時間。此外，現在的編輯器具備強大的補完功能，因此也未必所有使用靜態語言的工程師，都能夠對「型別安全」或「編譯器行為」等有正確概念，有些可能只是按照感覺來編寫程式。

這也就是為何在開頭提到「某種程度上是真實的」，一旦掌握了現場所需技術，就不太可能會因為日後不再持續學習而失去工作，從這層意義上來看，將會有所抵觸。

另外，近來在與工程技術的領域中，出現像 ChatGPT 和 GitHub Copilot 這樣的創新 AI 相關服務，並且有顯著發展；但我認為不是所有技術人員，都需要不斷追蹤這些最新資訊。即使是創新的技術或服務，在實際導入現場時也會漸進式地逐步發展。當然，追蹤最新技術趨勢並沒有壞處，但若沒有足夠的技術興趣或體力，那麼根據目前工作職場對於導入技術的氛圍，在必要時把握需要的訊息，也能夠足以生存下去。

對於那些對技術不感興趣的人來說，沒有必要自己開闢道路，只需要感謝前人鋪好的道路，並堂堂正正地前進就好。

如果沒有興趣就不能持續學習嗎

對於這一點，我認為明顯是錯誤的。

即使沒有興趣也可以學習

很顯然地，即使沒有興趣也可以學習，興趣和行動應該分開思考。

就我自己而言，即使對某種技術沒有興趣，只要目前的工作有需要，或者對未來的職涯發展有必要，我會在休息日抽出時間學習，這並不是什麼特別的事情。

在成為工程師之前，我曾在金融機構工作。當我看到周圍的同事，不一定都對「金融」感興趣，甚至可以說，對金融感興趣的人還比較少。

然而，他們在下班後或休息日也會學習。這是因為，這些對當前工作或未來晉升是必要的。

工程師也是一樣的，只要對當前工作執行或能夠接近自己未來的理想，那麼無論是否感興趣，學習就會是必要的。

相較於其他職業，我認為工程師更傾向將興趣和行動視為不可分割，但實際上，有許多行業即使沒有興趣也必須學習，甚至是在工作之外，學習的情況並不少見。在經歷高中或大學入學考試的人當中，有多少是因為對學術有興趣而學習的呢？

題外話：工程師和懈怠

這並不僅限於這部分，但這些只代表個人觀點，並且未經過科學根據的調查。由於主題涉及到個人性格，因此特別強調這只是我的猜測。

在社群上看到工程師的貼文時，經常能看到「懶惰」或「麻煩」的詞語。雖然只是主觀感受，但相較於非工程師的貼文，這些詞語似乎更常見。

容易懈怠的人，擁有對感興趣的事物非常專注這項優點，甚至到可能忘記時間的程度。然而，另一方面，對於不感興趣的事物，可能難以保持專注。如果是對技術感興趣的工程師，這可能不是問題，但如果沒有興趣，那可能就是悲劇了。

「對技術不感興趣的人不適合成為工程師」的觀點，也許被誤解為與這部分有關。可能因此產生「懈怠的人對不感興趣的事情難以保持專注」 + 「懈怠的人需要學習技術才能成為工程師」 => 「對技術不感興趣且懈怠的人不適合成為工程師」這樣的論點。

20230814 註記

在評論中，有讀者指出，在工程師的貼文中經常看到「懶惰」這個詞，這可能與 Larry Wall 所提倡程式工程師的三大美德之一「懶惰」有關。確實，在這種語境和含義使用是很有可能的。

首先是作為公司職員而不是工程師

這裡只討論在組織中工作的工程師。

在組織中工作，評價一位工程師價值的標準，將取決於如何為該組織創造利益，而技術能力只是其中的一種手段。

如果是這樣，即使對最新技術不感興趣或缺乏知識也沒關係，只要能把握該組織所採用的技術，並能用來解決組織的問題就足夠了。

即使只能使用過時的技術，對最新技術一無所知，只要能用自己的技術解決所屬組織的問題，那麼這個人就是一個出色的工程師，同時也是一位職員。

成為職業的工程師

在組織中工作，用自己的能力為組織貢獻利益是理所當然的。如果身為一名工程師，那麼方法通常會是基於技術的工程。

若是如此，對技術是否感興趣並不重要。因為動機更簡單，只需「學習對組織利益有貢獻的事情」，這樣就足夠了。將興趣和行動分開，採取「因為需要而學習」的態度非常重要。

如果不能學習對工作必要的知識，那麼不論是否適合成為工程師，也很難成為能被組織認可的人才。

面對未來的態度

如果已滿足於現在（目前工作職務）的需求，那麼只需要對未來做好準備，就不會有任何不安了。如果未來有想要成為的樣貌，那就朝著那個目標努力。然而，對於那些沒有未來目標，但仍想以工程師身份生活下去的人，以下將介紹一些我自己正在實踐的方法。

取得證照

我個人推薦的方法之一，是參加每年兩次由 IPA（資訊處理推進機構）舉辦的「情報処理技術者試験（資訊處理技術者試驗）」。如此可以避免一年中完全沒有學習的時期，且由於一年舉辦兩次，也不需每天忙於準備考試。

之所以選擇 IPA，是因爲資格沒有有效期限。一旦取得資格，就可以永遠列在履歷表上。對於對技術不感興趣的人來說，可能不太願意花時間在只有 2、3 年有效期限的資格上。

※ 關於「情報処理安全確保支援士（資訊處理安全支援專家）」，由於是採取註冊制度，因此說沒有有效期限可能不太準確，詳細資訊請參考 IPA 官方網站。

如果是身為 Web 工程師，基本資訊、應用資訊、資訊處理安全確保支援師、網路專家、資料專家、系統架構師等資格，都與實務相關，擁有這些資格也不會有損失。此外，根據自身的情況，參加專案經理的考試也是不錯的選擇。

在完成 IPA 必要的試驗後，可以參加 LPI（Linux Professional Institute）、AWS、Oracle 等的認證測驗，只需在 Google 上搜索「工程師 證照 推薦」，選擇與自身工作相關認證，每年參加兩次測驗即可。

這裡需注意的是，不要考取太多證照。假設對技術不感興趣，那麼每天為了學習某個領域將會非常痛苦。將認證視為對未來的準備，能有一層安全網應對可能情況，因此在不超出能夠容忍的範圍內學習就足夠了。

此外，這裡並不打算討論工程師證照是否有其必要性的問題，但我認為擁有相關資格總是有益的。特別是對於像我這樣對技術不感興趣的人來說，不太可能採取將個人開發成果上傳到 GitHub 這類的行動，因此證照可能是唯一能夠客觀證明 IT 技能的方式。我的 GitHub 個人帳號已經荒廢許久，最近某汽車公司的除草劑成了熱門話題，我甚至懷疑是否也散布到了我的 GitHub 上。

順帶一提，有時在就業市場上，經常會聽到「實務經驗比證照更重要」的看法。由於有些人在面試中善於說真假話，除了依賴由個人主觀認定在過去工作中的貢獻度，證照資格也應該列入評估對象。無論這個人是否能執行與該資格相應的實務工作，至少存在「在某個時刻滿足取得該資格的要求」這項事實。而在工作中，能否按時交付成果也非常重要。

閱讀技術書籍

只需閱讀就可以。我通常每天閱讀約 30 頁技術書籍。因為覺得麻煩，所以不會打開編輯器寫程式碼，只是閱讀而已。這樣就不會花太多時間，也不會感到負擔，僅僅閱讀就可以在某種程度上加深對技術的理解。

「看」影片

在 YouTube 或 Udemy 等平台上，觀看影片內容，這裡重要的是「看」而不是「觀看」。即使試圖「認真觀看」來完全理解，但如果對內容不感興趣，也不太能持之以恆，最終可能會發現自己正在看其他內容。當然，也不需要打開編輯器。（即使打開也無妨）

為了能夠保持適度的專注，只需專心「看」就好。人類的大腦和五感是很神奇的，即使只存在過去腦海中模糊的記憶，「啊，是那時候的某項事物」也可能像這樣在未來產生連結。

和工程師朋友出去吃飯

和工程師朋友一起吃飯時，總會有段時間談論技術相關的話題。在這個過程中，還可以瞭解最新的技術趨勢。

我有個非常熟悉區塊鏈技術的朋友。因為想知道他對區塊鏈的哪一方面感興趣，於是我閱讀了有關區塊鏈的書籍和觀看相關影片內容，查看了他的成果，甚至嘗試自己撰寫程式碼。結果，我對於區塊鏈技術有了一定程度的理解。

像這樣，即使對技術沒有興趣，只要對某個人感興趣，也許有機會透過這個人去瞭解某些技術。

關注 X 的技術用戶

我經常查看在 X 上所關注技術專家的貼文。這樣一來，我可以粗淺瞭解技術領域正在討論的話題。

在撰寫本文時，我觀察到有關「Ruby 的 return 語句」的小爭論。僅僅只是觀察一些關於這方面的貼文，也可以學習到「原來技術人員是用這種角度看待語言的」。

嘗試去做不感興趣的事情

取得證照、閱讀技術書籍、觀看影片等，做這些事情，可能會讓人懷疑自己其實對技術感興趣。因此，以下將依時間順序介紹今天的行動：

如上所示，我通常將大部分的時間花在 YouTube 和 Netflix 上。說個題外話，但我目前非常熱衷於 TBS 電視台的「日曜劇場」節目正在播放的《VIVANT》劇集，經常花很多時間回顧主要劇情，或觀看關於這部劇的分析影片。

雖然有點偏題，但我想傳達的是，正因為沒有興趣，學習才具有其價值。

即使可能存在細微差別，但那些在 X 上追蹤的人，無論是否有動力，都會強迫自己投入一定的時間完成某件事，期望由此產生（內在）動機，可以用 「念能力攻擊」 這個詞來形容。

努力學習不感興趣的事物，往後也可能因此產生興趣。

相對於對技術感興趣的人，那些不感興趣的人能勝過嗎

很遺憾的，越是追求卓越，越難在技術能力和知識方面，勝過那些對技術有濃厚興趣的人。如果對技術感興趣的人每天花 3 小時學習，而對技術不感興趣的人來說，花 4 小時學習就有辦法勝過嗎？這並不是那麼簡單的問題。

對技術充滿興趣的人，除了在桌前學習，還會在日常生活的各種場合，思考與技術相關的事情，例如上廁所、吃飯或散步時，也許在這些時候花的時間更長。

因此很遺憾的，面對這樣的人，不抱持興趣的一方是無法與其競爭的。原因很單純，因為面對技術的學習時間、量和質都不同。

但也不必感到過於悲觀，因為在我觀察的範圍內，這樣的人只佔極少數，只要能不懈怠地持續必要的學習，就能獲得在多數環境通用的技術能力。

此外，即使身為工程師，並不意味著單靠磨練技術就足以生存。能夠進行技術性討論的前提，是建立在能與客戶進行談判的能力、與工程師之間橫向協作的能力、領導其他工程師的能力、管理技術工程師團隊的能力等等，除了單純的技術能力以外，實際工作中所需的技能範圍非常廣泛。

儘管如此我仍然認為自己適合成為工程師

到目前為止，作為一名對技術不感興趣的工程師，我寫下自己對此的看法與實踐。儘管我依舊對技術不抱持興趣，但我仍然認為自己適合成為一名工程師。以下是我的原因。

喜歡細節工作

在工程領域中，包含許多細節工作。不用說，光是缺少冒號就可能導致無法運作，或空格變全形可能導致故障發生。然而，近來這些問題通常能被編輯器自動處理，這讓我有點嫉妒。
不僅是在寫程式的時候，在建立設計文件等情況，只不過是為了微調樣式，需要刪除字句、添加標點符號、修正錯字，或按上司喜好做細部調整，像這樣細緻而簡單的工作，我個人非常喜歡。

能夠迅速看到成果

只需添加一行程式碼，即可修復故障的功能，並且結果能夠立即顯示在螢幕上。例如，為了解決「這部分的數字沒有顯示」的問題，只需打開編輯器，稍微修改一下程式碼，然後刷新畫面，問題就解決了。

如果稍微拓寬視野，可以在許多場合迅速應用所學知識。這樣的例子多不勝數，如果被分配到的工作需要用到自己不熟悉的技術，透過自身研究和學習能夠成功完成這項工作，多數工程師可能或多或少都曾有過這些經歷。

如此一來，對於輸入和行動，能夠迅速看到結果，以及透過所學知識完成工作的實感，都使我樂在其中而不會感到厭倦。

「喜愛」所具有的熱度

如同再三提到的，雖然我個人對技術沒有太大興趣，但周圍有許多人是因為熱愛技術，才選擇擔任工程師。與其他職業相比，真正對工作充滿興趣的人可能佔據相當大的比例。

在這樣的環境中，可能有機會體驗到珍貴的時刻。雖然無法完全用言語表達，但面對某人的「喜愛」所散發的熱度，能夠意識到周圍的人，甚至是自己都被這份熱情所牽引。

「喜愛」這份情感所蘊含的熱情，感覺似乎遠遠超乎我們的想像。

著迷於網路的動力

無論是在網路上，還是私有網路空間，當別人向我建立的程式發送請求，並藉由回應滿足使用者的需求，可說是身為工程師所能夠體會到的最強大動力。

此外，自己完成的程式能透過網路向全球公開，並且被陌生人使用，這點讓我感到非常浪漫，甚至帶來一種興奮感。

喜歡尋求自己的美感

程式碼中存在著「美感」，即使是具有相同功能的程式碼，有的可能很髒亂，而有的可能具有令人嘆為觀止的美麗。

當然必須優先考慮的，是專案的程式碼規範，以及響應速度和內存效率等性能指標，但在滿足這些要求後，還存在一些空間，能夠寫出自己認為充滿美感的程式碼。這已不再被稱作是重構，而是類似補妝或盆景的至高領域了。

如上所述，雖然我對工程技術本身並不感興趣，但透過工程領域獲得的經驗讓我樂此不疲，並且使我認為自己適合成為工程師。

最後

基於以上這些理由，我認為並不一定要對技術感興趣，才能夠成為一名工程師。

即使對技術不感興趣，只要能夠發揮組織所需的能力，就不需擔心謀生的問題，有些人可能更關心透過工程領域所獲得的經驗。
此外，即使現在沒有興趣，也不代表將來會一直如此。

最後，我想分享這段話：

頂への途を見つけたなら険しいのか？己に向いているのか？可能なのか？そんなものは関係ない　”ただ登る”少なくとも俺にアメリカンフットボールを教えたマルコという男はそうしてきた才能が足りぬのなら臆面もなく人の手にすがり己の手を汚し愛する者に侮辱され　それでもなお頂点を獲るために全ての男が本来持っている焼け付くような渇き　ただ頂点を獲るために！by アイシールド21 峨王力哉

內容翻譯如下：

既然看到了通往頂點的路；危險嗎？自己夠格嗎？可能嗎？這根本就無所謂了。只要「往上爬」，至少——那個教會我美式足球的男人，就是那麼做的啊！力量不夠那就用卑鄙的手段也要得到，即使弄髒自己的雙手；即使被喜歡的人輕視。就算是那樣，也要爬上頂點。所有人心裡本就該存在的那種熊熊燃燒的渴望，就只為了登上頂點！
——摘自《光速蒙面俠21》峨王力哉

並不是說在這個時刻一定要追求巔峰。但如果有需要，不論自己是否適合，只要為了滿足這種需求，就應該「繼續往上爬」。

我相信這樣一來，絕對能夠以工程師的身份謀生。

到這裡，結束鐵人賽最後一篇文章！（撒花）雖然有點爆字數，差點以為要來不及-_-;;

看到這篇標題的時候不禁想著，不僅限於工程師這項職業，也許多數人對於工作本身的想法是：

勞動就是狗屎。（労働はクソということです。）
by《咒術迴戰》七海健人

咳咳、我想表達的是，或許大多數的人可能都曾懷疑過自己，懷疑是否有能力從事這份工作，但卻因為各種原因堅持下來。我想這沒有錯，畢竟能夠將興趣和工作完美結合的天選之人，在世上可能只佔極少數，但即使不感興趣，若能夠從中獲得成就感，也是很棒的事情呢。

最後，預計明天會再整理一篇結語，為今年鐵人賽初體驗做個結尾，以上！

15th鐵人賽目錄傳送門：https://ithelp.ithome.com.tw/users/20135558/ironman/6290