Gemini API Node.js 教學：在 VPS 或本機建立可正式開發的 Google AI 環境

這篇比較適合你已經不只是想「玩一下 CLI」，而是準備在 Node.js 專案裡正式呼叫 Gemini API。很多中文教學還停留在舊套件、舊模型名稱或直接把 API Key 寫死在範例裡，短期看起來能跑，長期很容易變成維護災難。

所以這篇會直接用目前官方文件的做法整理給你，讓你知道現在比較穩的 SDK 是什麼、環境變數該怎麼放、第一支測試程式怎麼寫，然後再帶你進入串流回應、function calling、safety settings、多模態 API 和 structured output 這些進階用法。

先把核心觀念弄對

• Google 官方現在在 JavaScript 範例裡使用的是 @google/genai
• 第一支程式先用最小可用範例驗證 GEMINI_API_KEY、SDK 與網路連線，再考慮串進產品邏輯
• 想做長期維護，就不要把金鑰直接寫在程式裡，也不要照抄過時的套件名稱
• 串流回應和 function calling 是把 Gemini 接進正式產品的兩個關鍵能力

這篇比較適合哪些情境

• 想在 Node.js 專案裡接入 Gemini 做內容生成、摘要、問答或資料處理的人
• 想先在本機或 VPS 驗證 API，之後再串進網站、後台或自動化服務的人
• 已經有 JavaScript 基礎，但不想被過時範例拖慢的人
• 想用 function calling 讓 AI 呼叫你自己的工具和 API 的人

開工前先準備好這些東西

• 準備好 Node.js 專案，還沒有的話先 npm init -y
• 到 Google AI Studio 申請 GEMINI_API_KEY
• 確認你會用 .env 或 shell 環境變數管理敏感資訊

詳細教學與操作步驟

如果你要在 Node.js 專案裡正式呼叫 Gemini，先把 SDK 與金鑰管理方式打對很重要。依 Google 官方目前的 JavaScript 文件，最直接的做法是使用 @google/genai，搭配 GEMINI_API_KEY 環境變數，再用最小範例確認回應正常。

為什麼先從最小範例開始，而不是直接接進產品？

因為你一開始要排除的變數很多，包括 SDK 是否裝對、API Key 是否有效、機器是否能連到 Gemini API、模型名稱是否可用。先把最小範例跑通，後面再接 Express、Next.js API Route 或 queue worker，會省很多時間。

步驟一：取得 Gemini API Key

1. 登入 Google AI Studio。
2. 在左側選單點選「Get API Key」。
3. 點選「Create API Key in new project」。
4. 複製產生的金鑰，稍後會用到。

步驟二：在專案中安裝官方 SDK

進入你的專案目錄後，安裝官方目前文件使用的 JavaScript SDK：

npm install @google/genai

如果你看到很多文章還在用舊套件名稱，先不要急著照抄。能不能跑是一回事，之後跟官方文件同步與維護會不會痛苦是另一回事。

步驟三：先設定 GEMINI_API_KEY，再寫測試程式

不要把金鑰直接寫死在程式內。先在 shell 設定：

export GEMINI_API_KEY="YOUR_API_KEY"

接著建立 index.mjs 或在支援 ES Modules 的環境中撰寫測試：

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "請用一句話介紹侃瑞科技 VPS 的優點。",
  });

  console.log(response.text);
}

await main();

步驟四：執行與驗證

在終端機執行：node index.mjs。如果有收到正常文字輸出，代表你的 SDK、金鑰與網路都已經通了。這時候再開始封裝成自己的 service 或 API route，風險會小很多。

步驟五：串流回應 — 讓使用者即時看到輸出

對使用者體驗來說，等整個回應產完再顯示是很糟的。串流回應讓你的應用可以邊生成邊顯示：

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function streamExample() {
  const response = await ai.models.generateContentStream({
    model: "gemini-2.5-flash",
    contents: "寫一篇 300 字的 VPS 選購指南。",
  });

  for await (const chunk of response) {
    // 每一塊文字到達時立刻輸出
    process.stdout.write(chunk.text || "");
  }
  console.log(); // 換行
}

await streamExample();

串流回應在以下場景特別重要：

• 聊天介面 — 讓使用者看到「AI 正在打字」的即時效果
• 長文生成 — 不用等 30 秒才看到完整結果
• 即時分析 — 邊分析邊回報進度

如果你要在 Express 或 Next.js 中使用串流，可以搭配 Server-Sent Events（SSE）：

// Express 範例
app.get("/api/stream", async (req, res) => {
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");

  const response = await ai.models.generateContentStream({
    model: "gemini-2.5-flash",
    contents: req.query.prompt,
  });

  for await (const chunk of response) {
    res.write(`data: ${JSON.stringify({ text: chunk.text })}\n\n`);
  }

  res.write("data: [DONE]\n\n");
  res.end();
});

步驟六：Function Calling — 讓 AI 呼叫你的工具

Function calling 讓 Gemini 不只能生成文字，還能呼叫你定義的函式。這是建構 AI agent 的核心能力：

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

// 定義工具
const tools = [
  {
    functionDeclarations: [
      {
        name: "get_server_status",
        description: "查詢指定伺服器的目前狀態",
        parameters: {
          type: "object",
          properties: {
            server_id: {
              type: "string",
              description: "伺服器 ID，例如 vps-001",
            },
          },
          required: ["server_id"],
        },
      },
      {
        name: "get_pricing",
        description: "查詢 VPS 方案的價格",
        parameters: {
          type: "object",
          properties: {
            plan: {
              type: "string",
              enum: ["nano", "xs", "s", "m", "l", "xl"],
              description: "VPS 方案名稱",
            },
          },
          required: ["plan"],
        },
      },
    ],
  },
];

// 實際的函式實作
function getServerStatus(serverId) {
  // 實際上會查資料庫或 API
  return { status: "running", uptime: "99.9%", cpu: "12%" };
}

function getPricing(plan) {
  const prices = {
    nano: 900, xs: 1500, s: 2200,
    m: 4500, l: 9000, xl: 18000,
  };
  return { plan, monthly: prices[plan], currency: "TWD" };
}

async function functionCallingExample() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "我想知道 M 方案的價格，還有 vps-001 的狀態",
    config: { tools },
  });

  // 處理 function call 回應
  for (const part of response.candidates[0].content.parts) {
    if (part.functionCall) {
      const { name, args } = part.functionCall;
      let result;

      if (name === "get_server_status") {
        result = getServerStatus(args.server_id);
      } else if (name === "get_pricing") {
        result = getPricing(args.plan);
      }

      console.log(`Function ${name} called:`, result);
    }
  }
}

await functionCallingExample();

Function calling 的典型應用場景：

• 客服機器人 — 查訂單、查伺服器狀態、查帳單
• 管理後台 — 讓 AI 助手操作資料庫查詢和報表
• 自動化流程 — 讓 AI 決定什麼時候該呼叫哪個 API

步驟七：Safety Settings — 控制內容安全

Gemini API 預設有內容安全過濾。如果你的應用場景需要調整，可以透過 safety settings 設定：

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "分析這段程式碼的安全漏洞。",
  config: {
    safetySettings: [
      {
        category: "HARM_CATEGORY_DANGEROUS_CONTENT",
        threshold: "BLOCK_ONLY_HIGH",
      },
      {
        category: "HARM_CATEGORY_HARASSMENT",
        threshold: "BLOCK_MEDIUM_AND_ABOVE",
      },
    ],
  },
});

常見的 threshold 等級：

步驟八：多模態 API — 處理圖片和檔案

Gemini 原生支援多模態輸入，你可以在 API 請求中同時傳文字和圖片：

import { GoogleGenAI } from "@google/genai";
import fs from "fs";

const ai = new GoogleGenAI({});

async function analyzeImage() {
  const imageData = fs.readFileSync("screenshot.png");
  const base64Image = imageData.toString("base64");

  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
      {
        parts: [
          { text: "這張截圖有什麼 UI 問題？" },
          {
            inlineData: {
              mimeType: "image/png",
              data: base64Image,
            },
          },
        ],
      },
    ],
  });

  console.log(response.text);
}

await analyzeImage();

多模態 API 的實際用途：

• UI 測試 — 讓 AI 分析截圖是否符合設計稿
• 文件處理 — 分析上傳的 PDF 或圖片內容
• 監控告警 — 分析伺服器監控圖表的異常

步驟九：Structured Output — 讓 AI 輸出結構化資料

如果你需要 AI 輸出 JSON 格式的結構化資料（而不是自由文字），可以用 response schema：

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "分析這三個 VPS 方案：Nano、S、M",
  config: {
    responseMimeType: "application/json",
    responseSchema: {
      type: "array",
      items: {
        type: "object",
        properties: {
          plan: { type: "string" },
          recommended_for: { type: "string" },
          pros: { type: "array", items: { type: "string" } },
          cons: { type: "array", items: { type: "string" } },
        },
        required: ["plan", "recommended_for", "pros", "cons"],
      },
    },
  },
});

// response.text 會是合法的 JSON 字串
const analysis = JSON.parse(response.text);
console.log(analysis);

Structured output 特別適合：

• 資料擷取 — 從非結構化文字中擷取特定欄位
• 分類任務 — 讓 AI 輸出固定格式的分類結果
• API 回應 — 直接把 AI 輸出當成 API 回應傳給前端

常見問題

Q：為什麼回應顯示認證錯誤？ 先檢查 GEMINI_API_KEY 是不是有真的 export 進目前 shell，而不是只寫在某個檔案裡卻沒載入。

Q：為什麼我照舊教學安裝卻跟官方範例長不一樣？ 因為 Google 的 SDK 與範例有持續演進。若你發現文章還在教你使用不同套件名稱或更舊的模型，建議回頭以官方文件為主。

Q：串流回應和一般回應有什麼效能差異？ 總回應時間其實差不多，但串流讓使用者更早看到第一個字。對使用者體驗來說，感知等待時間會大幅降低。

Q：function calling 有呼叫次數限制嗎？ Function calling 本身沒有額外限制，但每次呼叫都算 API token 用量。如果你的工具定義很多，token 消耗會增加。

Q：多模態輸入有檔案大小限制嗎？ 有。inline data 有大小限制，大型檔案建議先上傳到 Google Cloud Storage 再引用 URI。具體限制請查官方文件，因為會隨版本調整。

做完後怎麼確認自己真的可開發

• 關掉目前 shell，重開一個新的 shell 再測一次，確認環境變數不是只在單次 session 有效
• 把 prompt 改成你自己的業務內容，確認不是只有範例句子能跑
• 測試串流回應，確認 chunk 可以正確接收
• 測試 function calling，確認 AI 會正確呼叫你定義的工具
• 嘗試把程式包成一個簡單函式或 API route，看你目前專案結構有沒有順利接住

這一題最常踩的坑

• 直接照抄舊版文章，結果套件名稱、模型名稱、寫法都跟官方最新版不一致
• API Key 放在程式碼裡，之後一 push 到 Git 就變成安全事故
• 一開始就把 Gemini 接進正式流程，卻還沒用最小範例排除認證與配額問題
• 串流回應沒有做錯誤處理，中途斷線就整個 crash
• Function calling 的工具定義太模糊，AI 搞不清楚什麼時候該呼叫哪個工具
• Structured output 的 schema 太複雜，AI 反而容易產出不合格式的回應

如果你要往下一步走

如果你是先從 CLI 開始試 Gemini，下一步就可以把它接進真正的 Node.js 專案邏輯。反過來說，如果你連 Node.js 版本管理都還沒整理好，建議先回頭補 Node.js 與 NVM 教學，不然 SDK 一更新，你的開發機很容易又亂掉。想了解 Gemini CLI 的使用方式，可以看 Gemini CLI 安裝教學。如果你也想串接 OpenAI 的 API，可以參考 OpenAI API (Python) 開發環境安裝教學。