侃瑞科技

Gemini CLI 安裝教學：在 VPS 或本機終端機直接使用 Google 的 AI CLI

完整 Gemini CLI 安裝與進階設定：Google OAuth 與 API Key 差異、Vertex AI 企業整合、GEMINI.md 規則檔、多模態功能、Google 搜尋整合、MCP 擴充，一次搞定。

GeminiGemini CLIGoogle AIAI 工具VPS安裝教學Node.jsGEMINI.md多模態Google 搜尋MCPVertex AI自動化命令列

Gemini CLI 這類工具最容易出現的問題，不是安裝指令本身，而是你照著做完後，還是不知道該選 Google 登入還是 API Key、Node.js 要多少版本、在 VPS 上到底適不適合直接跑、以及安全界線應該畫在哪裡。這篇會把這些問題一起講完。

除了基本安裝和認證，這篇會深入三種認證方式的差異、GEMINI.md 進階用法、多模態功能（分析圖片與檔案）、Google 搜尋整合、MCP server 擴充，以及怎麼在實際開發場景中活用 Gemini CLI。

先抓住這三個判斷點

  • Gemini CLI 官方目前要求 Node.js 20+，這點比很多舊文章寫的版本還新。
  • 個人測試最省事的方式通常是直接用 Google 帳號登入；要做明確配額與帳務管理，再考慮 API Key。
  • 這類 AI CLI 會碰到檔案與 shell 指令，安裝完要一起檢查權限與信任邊界，不是只有能執行就算完成。

什麼人讀這篇會最有幫助

  • 想在終端機直接讓 Gemini 幫你看專案、產說明、改腳本或整理重點的人
  • 想先用免費額度試用，再決定要不要把它納入日常工作流的人
  • 想把 Gemini CLI 跟本機資料夾、MCP 或自動化流程接起來的開發者
  • 需要分析圖片、截圖或多模態內容的人

開始安裝前先確認

  • 確認你的 Node.js 是 20 以上
  • 決定你要走 Google OAuth 還是 GEMINI_API_KEY
  • 如果你要在正式專案或敏感伺服器上使用，先評估哪些資料夾可以讓 CLI 讀，哪些不該碰

詳細教學與操作步驟

Gemini CLI 是 Google 開源的終端機 AI agent。依官方 README，目前最常見的啟動方式包含直接用 npx 試跑、用 npm 全域安裝，或在 macOS / Linux 用 Homebrew 安裝。對多數 Linux VPS 使用者來說，npm 仍然是最直覺的入口。

為什麼要用官方 Gemini CLI，而不是第三方包裝版？

官方版本更新快，功能也比較完整。根據官方 README，它支援 Google 登入、Gemini API Key、Vertex AI、MCP、自訂 GEMINI.md 上下文，以及非互動模式輸出 JSON。這些能力對想把 CLI 真的放進工作流的人很重要。

步驟一：使用 npm 進行安裝

官方文件列出的前提是 Node.js 20 或以上。如果你還沒裝好環境，先看我們的 Node.js 安裝教學。安裝方式如下：

npm install -g @google/gemini-cli

如果你只是想快速試跑，也可以直接用 npx https://github.com/google-gemini/gemini-cli。但要長期使用、想固定版本與 shell 命令，還是建議正式安裝。

macOS 使用者也可以用 Homebrew：

brew install gemini-cli

步驟二：深入理解三種認證方式

輸入 gemini 後，CLI 會引導你選登入方式。這三種方式各有適用場景，選錯會讓你後面很痛苦：

方式一：Login with Google（個人開發最推薦）

適合個人開發者和試用階段。登入 Google 帳號後，你會獲得 Google AI 免費額度。

優點：

  • 不需要管理 API key
  • 免費額度足夠個人開發測試
  • 登入一次，session 會記住

限制：

  • 免費額度有請求次數與 token 上限
  • 無法精確控制計費
  • 不適合正式產品環境

方式二：Gemini API Key（明確計費與配額管理）

先在 Google AI Studio 申請，再設定環境變數：

export GEMINI_API_KEY="YOUR_API_KEY"

優點：

  • 明確的配額與計費控制
  • 可以為不同專案建立不同 key
  • 適合自動化流程和 CI/CD

限制：

  • 需要自己管理 key 的安全性
  • 要注意不能把 key commit 進 repo

如果你要長期使用，建議把環境變數寫進 shell 設定檔：

# ~/.bashrc 或 ~/.zshrc
export GEMINI_API_KEY="YOUR_API_KEY"

方式三：Vertex AI（企業與正式環境）

偏企業用途，會牽涉到 Google Cloud 專案與計費設定：

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_REGION="us-central1"

優點：

  • 企業級的存取控制與審計
  • 可以用 IAM 管理誰能呼叫 API
  • 支援 VPC Service Controls

限制：

  • 設定複雜度高
  • 需要 Google Cloud 帳號和計費設定

建議： 如果你只是先試功能，Google 帳號登入最省時間。如果你已經決定要正式使用，API Key 會更明確。企業環境才需要考慮 Vertex AI。

步驟三：設定 GEMINI.md — 讓 Gemini 理解你的專案

跟 Claude Code 的 CLAUDE.md 類似，Gemini CLI 會讀取 GEMINI.md 作為專案上下文。

GEMINI.md 層級架構

~/.gemini/GEMINI.md           # 全域（個人偏好）
{repo-root}/GEMINI.md         # 專案層級（commit 進 repo）
{repo-root}/src/GEMINI.md     # 子目錄層級

一份實用的 GEMINI.md 範例

# GEMINI.md

## 專案概述
這是一個 Next.js 靜態網站，用於銷售主機服務。

## 技術棧
- Next.js 16 + App Router
- Tailwind CSS v4
- TypeScript strict mode

## 常用指令
- npm run dev — 開發伺服器
- npm run build — 靜態建置
- npm run lint — ESLint 檢查

## 文案規範
- 所有 UI 文案使用繁體中文
- 技術詞保留英文（API、CLI、SDK）
- 公司名稱：侃瑞科技

## 注意事項
- 靜態匯出，不能用 server-side 功能
- Tailwind v4 設定在 globals.css，沒有 tailwind.config.js

步驟四：多模態功能 — 不只是文字

Gemini CLI 的一大優勢是原生支援多模態。你可以直接把圖片、截圖甚至 PDF 丟給它分析：

# 分析截圖中的 UI 問題
gemini "看這張截圖，告訴我 CSS 哪裡跑版了" < screenshot.png

# 分析錯誤截圖
gemini "這個 error log 截圖是什麼問題？" < error.png

# 分析設計稿
gemini "這份設計稿要怎麼用 Tailwind 實作？" < design.png

在互動模式中，你也可以直接引用檔案：

gemini
> @screenshot.png 這個 UI 有什麼可以改善的地方？

步驟五：Google 搜尋整合 — 即時查文件

Gemini CLI 可以結合 Google Search 來回答需要最新資訊的問題。這是其他 AI CLI 工具不太容易做到的：

gemini "搜尋 Next.js 15 的 breaking changes 有哪些"
gemini "查一下目前 Node.js LTS 是哪個版本"
gemini "找 Tailwind v4 的 migration guide"

這個功能在以下場景特別有用：

  • 查最新版本的 API 文件
  • 找特定錯誤訊息的解決方案
  • 比較不同工具或框架的差異
  • 找最新的安全漏洞通報

步驟六：MCP 擴充 — 讓 Gemini 連接更多工具

Gemini CLI 支援 MCP（Model Context Protocol），讓你接入更多外部工具：

在 ~/.gemini/settings.json 中設定：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token"
      }
    }
  }
}

步驟七：非互動模式與自動化 — 接進 CI/CD

如果你要把 Gemini CLI 接進 shell script 或 CI，官方支援 prompt mode 和結構化輸出：

# 單次提問，直接輸出結果
gemini -p "Explain the architecture of this codebase"

# JSON 輸出，方便程式解析
gemini -p "列出這個 repo 的主要模組" --output-format json

# 串流 JSON 輸出
gemini -p "分析 package.json 的依賴" --output-format stream-json

# 指定模型
gemini -m gemini-2.5-flash -p "快速摘要這個 PR 的變更"

實際的自動化範例：

#!/bin/bash
# 自動產生 commit message
DIFF=$(git diff --staged)
MESSAGE=$(gemini -p "根據以下 diff 產生一個 conventional commit message：$DIFF" --output-format text)
git commit -m "$MESSAGE"

步驟八：實戰場景

Debug 工作流

gemini "分析 error.log 最後 50 行，找出重複出現的錯誤模式"

Code Review 工作流

gemini "review 這個 PR 的變更，注意安全性問題"

文件生成工作流

gemini "根據這個 API route 的程式碼產生 OpenAPI 文件"

搭配截圖的 UI Debug

gemini "這張截圖跟設計稿差在哪裡？列出需要修改的 CSS" < current-ui.png

常見問題

Q：為什麼安裝完卻不能跑？ 先檢查 Node.js 版本。Gemini CLI 官方 README 明寫需要 Node.js 20+，很多舊環境卡在這裡。

Q：CLI 能不能拿來寫自動化？ 可以。官方支援 prompt mode 與 JSON 輸出，但你還是要先界定哪些資料可以送進模型、哪些 shell 動作不能自動放行。

Q：Google 登入的免費額度有多少？ 額度會隨 Google 的政策調整。建議到 Google AI Studio 查看你目前的用量與限制，不要假設額度永遠不變。

Q：多模態功能支援哪些格式？ 常見的圖片格式（PNG、JPG、WebP）都支援。PDF 也有基本支援，但大型 PDF 建議先拆分再處理。

Q：GEMINI.md 和 CLAUDE.md 會互相衝突嗎？ 不會。兩個檔案分別被不同工具讀取，完全獨立。但建議保持規則一致，避免你自己在不同工具之間產生混亂。

做完後怎麼確認自己真的能用

  • 跑一次 gemini 完成登入，不要只看 gemini --help
  • 實際在一個測試資料夾裡問它一題，例如請它總結目前目錄用途
  • 如果你用 API Key，就另外測一次 export GEMINI_API_KEY=... 之後的啟動流程，確認不是只有 OAuth 能跑
  • 測試多模態：丟一張截圖給它分析，確認圖片輸入功能正常
  • 如果你設了 GEMINI.md，請它列出它讀到哪些專案規則

這一題最常踩的坑

  • 還在用舊版 Node.js，結果 npm 裝得下來但 CLI 跑不動
  • 不清楚 OAuth 和 API Key 差異，一開始就把正式金鑰丟進測試機器
  • 把它當成普通聊天工具看，卻忘了它可能會碰檔案與 shell，安全設定沒先想好
  • 沒有寫 GEMINI.md，每次開 session 都要重新解釋專案背景
  • 不知道有多模態功能，結果手動把截圖轉成文字再貼給 CLI

如果你要往下一步走

Gemini CLI 裝好後，通常下一步會分成兩條路。如果你想寫應用程式，就接著看 Gemini API Node.js 教學。如果你想先把開發機環境打穩，就先把 Node.js 與 NVM 跟 Git SSH Key 一起補齊。想了解其他 AI CLI 工具，可以看 Claude Code 安裝教學 或 Codex CLI 安裝教學。

需要主機來實作？

侃瑞科技提供 cPanel 虛擬主機與 VPS，教學裡的操作開箱即用。

查看方案 →
上一篇

← Claude Code 安裝教學：在 VPS 或本機終端機直接用 Anthropic CLI 協助寫程式

下一篇

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

LINE 諮詢