小白的 Gemini CLI 安装指南

作者：一位AI助手和它耐心超凡的人类伙伴

在光鲜的软件世界里，通常只会看到“一键安装，轻松使用”的完美景象。但现实中，尤其是对于刚接触命令行工具的新手来说，安装过程往往是一场充满意外的冒险。这篇指南，诞生于我和AI之间一次长达数小时充满挑战的真实互动。我们一起从 gcloud 的迷宫一路奋战到 npm 的丛林，经历了“找不到命令”、“权限被拒绝”、“包名冲突”、“安装程序“偷懒””和“API密钥配置”等九九八十一难。最终，我们成功了。

我将这段宝贵的经历整理出来，把所有踩过的坑都标记清楚，并提供最终被验证有效的、最直接的解决方案。希望这篇“血泪史”能让真小白们少走弯路，丝滑地用上 Gemini CLI 这个强大的 AI 助手。

Gemini CLI: 你的开源终端 AI 代理

Gemini CLI 是 Google 最近发布的一款开源的、基于命令行的 AI 工具。你可以把它理解为一个直接生活在你电脑终端（Terminal）里的 AI 助手。它的核心目标是将强大的 Gemini 模型能力与开发者的日常工作流无缝集成，让你可以在不离开终端的情况下，通过自然语言完成各种开发任务。

如果你希望获得一个开放、免费且功能全面的终端 AI 助手，并且希望它能利用最新的网络信息来辅助你开发，那么 Gemini CLI 是一个绝佳的起点。特别是对于个人开发者和喜欢探索开源工具的人来说，它非常有吸引力。

我是一个开发新手，不怎么会用终端命令行，那用  Gemini CLI 是不是很困难？

这是一个非常好的问题，很多习惯图形界面（IDE）的开发者在初次接触命令行工具时都会有同样的顾虑。长话短说：对于新手来说，直接使用 Gemini CLI 会有一定的学习曲线，但它远比从零开始学习传统的命令行要容易得多。事实上，Gemini CLI 反而可以成为你学习和掌握终端命令行的“私人教练”。

对于习惯了图形界面的你来说，最主要的挑战在于：

• 从“点击”到“输入”：你需要从习惯于在 Xcode 中点击按钮（例如，添加文件、运行项目、提交代码）转换到在黑色的终端窗口里输入文字指令来完成同样的事情。这是一种工作习惯上的改变。
• 理解文件路径和目录：在终端里，你需要知道你的项目文件在哪里，并且使用 cd (Change Directory) 命令进入到正确的文件夹。这是使用任何命令行工具的基础，也是一开始最容易让新手感到困惑的地方。

这正是 Gemini CLI 的核心价值所在。它被设计出来，就是为了用自然语言替代那些复杂、难记的传统命令。它是你的命令行翻译和老师：这就像一个即时翻译！你用自然语言提问，它用命令行语言“作答”并执行。通过观察它的行为，你会潜移默化地学会很多实用的命令，下次你甚至可以尝试自己输入那些命令。

当你让 Gemini CLI 完成一个任务时，它不仅会帮你执行，很多时候它还会告诉你它在背后 实际使用 了哪个传统的命令行指令。新手使用终端时常常害怕输错命令导致文件被删除或系统出问题。使用 Gemini CLI 时，因为它首先会理解你的意图，所以执行破坏性操作的风险会小很多。你可以先问它“我打算删除所有编译产生的临时文件，应该怎么做？”它会告诉你安全的做法。

假设你想在 SwiftUI 项目中，查找所有包含单词 “deprecated” 的 .swift 文件。你可能需要学习并输入像 grep -r "deprecated" --include="*.swift" . 这样的命令。对于新手来说，这几乎是不可能记住的。而 Gemini CLI 方式：你只需要用中文输入 gemini "帮我查找这个项目里所有包含 'deprecated' 的 swift 文件"。Gemini CLI 会理解你的意图，并帮你执行这个操作。

给新手的建议：

1. 从简单任务开始：不要强迫自己第一天就完全抛弃 Xcode。你可以先从一些简单的、辅助性的任务开始使用 Gemini CLI，比如：gemini "重命名这个文件 'MyView.swift' 为 'UserProfileView.swift'；"gemini "用 SwiftUI 写一个简单的按钮，点击时打印 'Hello'"…
2. 把它当成“万能的帮助文档”：每当你想在终端里做什么，但不知道命令时，就去问 Gemini CLI
3. 学习最最基础的几个命令：只需学习三个最基本的命令，就能应对 90% 的场景。例如：pwd (Print Working Directory): 查看你当前在哪个文件夹。ls (List): 查看当前文件夹里有哪些文件和子文件夹。cd <文件夹名称> (Change Directory): 进入一个子文件夹。

准备工作：磨刀不误砍柴工

在开始之前，请确保你的 Mac 满足以下基本条件：

• Xcode Command Line Tools：这是苹果系统上进行任何开发的基础。打开终端，输入 xcode-select --install，如果尚未安装，系统会引导你完成。
• Node.js 和 npm：最稳定、官方的安装方式是通过 Node.js 的包管理器 npm。请在终端输入 node -v 和 npm -v 检查是否已安装。如果提示 command not found，请从 Node.js 官网 下载安装最新的 LTS 版本。

第1章：先安装 Google Cloud SDK

Google Cloud SDK (gcloud) 安装：从官网这里下载安装包最方便。安装完 google cloud cli 后，它提示说它和 python3.12 配合最好，于是问我要不要装 Python3.12 ，我同意了。于是运行时又报错…

失败的根源：SSL: CERTIFICATE_VERIFY_FAILED。如何解决？你需要手动告诉 Python 去哪里找到可信的证书。请去 /Applications/Python 3.12/ 文件夹，双击运行 Install Certificates.command。运行成功后，回到终端，输入 gcloud init 重新尝试初始化。

第2章：安装 Gemini CLI

官方推荐的安装方式非常简单，只需一行命令。但这里就埋着我们遇到的第一个大坑。正确的安装命令是：如果你的 npm 配置过无需 sudo 的全局安装，可以去掉 sudo。但对于大多数默认设置，sudo 是必需的，它会请求你的电脑密码。

sudo npm install -g @google/gemini-cli

【坑 #1：npm 上的“李鬼”——包名冲突】

我最初的错误，是运行了下面的代码。请注意，这里多加了一个叫 gemini 的包。而这个 gemini 是一个完全不相关的、用于UI测试的旧软件包。正是这个旧包，导致了一系列致命的编译错误（比如 fatal error: 'fp.h' file not found）。请务必确认你安装的是带有 @google/ 前缀的官方包 @google/gemini-cli，不要画蛇添足。

npm install -g @google/gemini-cli gemini

第3章：命令三大经典报错与对策

在 npm 显示安装成功后（added ... packages），你满怀期待地输入 gemini，却可能遇到一堵又一堵高墙。别怕，我们都经历过。

【坑 #2：zsh: command not found: gemini】

这是最经典的报错，意思是终端不知道 gemini 是个什么东西。原因：npm 安装了程序，但没有成功地在系统的“命令快捷方式”存放地（PATH 环境变量包含的目录）创建一个指向 gemini主程序的快捷方式（符号链接）。

解决方案：手动创建快捷方式

1. 找到 npm 全局安装的根目录。Bashnpm root -g 你会得到一个路径，例如 /opt/homebrew/lib/node_modules。请复制这个路径。
2. 手动创建符号链接（快捷方式）。 请将下面命令中的 【你的npm根目录】 替换为你上一步得到的真实路径。这条命令的作用，就是在 /usr/local/bin 这个所有终端都能找到的地方，创建了一个叫 gemini 的快捷方式，指向它真正的程序文件。

sudo ln -s 【你的npm根目录】/@google/gemini-cli/dist/cli.js /usr/local/bin/gemini 

【坑 #3：zsh: permission denied: gemini】

这个错误说明终端已经找到了 gemini 命令，但当前用户没有权限执行它。原因：通常是因为 npm 用 sudo (root权限) 创建了文件，但没给普通用户设置可执行权限。

解决方案：授予执行权限。用这条命令找到 gemini 的位置，并赋予其执行权限。

sudo chmod a+x $(which gemini)

【坑 #4：身份认证失败】

当运行 gemini 命令时，它可能会提示你需要设置 GEMINI_API_KEY。原因：程序本身可以运行了，但它需要一个“通行证”（API 密钥）才能和 Google 的 AI 服务器对话。

解决方案：获取并配置 API 密钥

1. 获取你的专属 API 密钥。 访问 Google AI Studio，登录并创建一个新的 API 密钥，然后复制它。【警告】 API 密钥等同于你的密码，请妥善保管，切勿泄露
2. 将密钥永久保存在你的终端环境中。 运行以下命令，记得把你自己的密钥粘贴进去
3. 让设置生效。 重启终端，或者运行 source ~/.zshrc

echo 'export GEMINI_API_KEY="【这里粘贴你刚刚复制的API密钥】"' >> ~/.zshrc

成功了！？还没有…

万事俱备，输入 gemini prompt "你好"，满怀期待地看着屏幕，却发现它打印了一长串帮助信息，并提示不认识 prompt… 原来命令语法也变了，新版的 Gemini CLI 用法不是 gemini prompt。正确的提问方式是：

gemini -p "你好，我们这次真的、真的成功了吗？"
gemini --prompt "你好，我们这次真的、真的成功了吗？"

当你看到终端里终于出现了来自 Gemini 的回答时，请尽情庆祝吧！

回顾一下，从 gcloud 的安装失败，到 npm 的包名冲突和编译错误，再到 PATH 环境变量的曲折配置，接着是 command not found，然后是 permission denied，再到发现安装程序根本没创建快捷方式，最后是命令语法的变化和 API 密钥的配置… 几乎把一个开发者可能遇到的所有环境配置问题都经历了一遍，并且最终靠自己的耐心和坚持解决了它。

这不仅仅是安装了一个工具，更是一次非常宝贵的、从零开始解决复杂问题的实战经验。这种解决问题的能力，比工具本身更有价值。为你超凡的耐心和坚持点赞！希望这篇指南能为你点亮前行的道路。现在，去享受 AI 带来的编程乐趣吧！