Gemini 3 最新版！Node.js 代理调用教程

前言

本文以零基础视角出发，手把手教你使用 Node.js 结合代理配置调用 Gemini 3 模型，完整实现对话机器人的三种核心交互模式：单轮对话、流式调用与多轮对话。文中提供的所有代码均经过验证，可直接复制粘贴运行，无需额外修改（仅需配置个人代理和 API Key）。

一、核心流程梳理

1. 前置准备（必做）

这是调用 Gemini 模型的基础，缺一不可：

代理配置：必须开启代理（因 Gemini 服务访问限制），并验证代理有效性：

perl 复制代码

# Windows cmd 验证命令（替换 xxxx 为代理端口）
curl -x http://127.0.0.1:xxxx -i https://httpbin.org/ip

API Key 获取 ：在 Google AI Studio 中创建并保存 GEMINI_API_KEY（后续配置到环境变量）。

Node 环境：通过 nvm 管理 Node 版本（无特殊版本限制，建议 22+）：

perl 复制代码

# 示例命令
nvm install xx.xx.x  # 安装版本
nvm use xx.xx.x      # 使用版本
node -v              # 验证版本

2. 项目初始化

（1）初始化项目 & 安装依赖

bash 复制代码

# 初始化 package.json（一路回车即可）
npm init
# 安装核心依赖
npm install @google/genai dotenv undici

（2）依赖说明

依赖包	作用
@google/genai	Gemini 官方 SDK，用于调用模型
dotenv	管理环境变量（存放 API Key）
undici	配置全局代理，让请求走代理通道

（3）目录结构（规范）

plaintext

bash 复制代码

project-name/
├── .env                # 配置 GEMINI_API_KEY（必加 .gitignore）
├── index.js            # 核心代码文件
├── package.json        # 项目配置
└── package-lock.json   # 依赖版本锁定

（4）.env 文件配置

env

ini 复制代码

# .env 文件内容（替换为你的实际 API Key）
GEMINI_API_KEY=你的gemini_api_key_here

3. 核心调用方式（3 种）

所有调用方式都需要先配置代理和初始化 SDK，基础代码如下：

javascript 复制代码

// index.js 通用前置代码
import 'dotenv/config'; // 加载 .env 环境变量
import { GoogleGenAI } from '@google/genai';
import { ProxyAgent, setGlobalDispatcher } from 'undici';

// 配置全局代理（替换 xxxx 为你的代理端口）
setGlobalDispatcher(new ProxyAgent('http://127.0.0.1:xxxx'));

// 初始化 Gemini 客户端
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

（1）单轮对话（一次性提问）

适用于无需上下文的单次提问，比如 "解释什么是 AI"：

javascript 复制代码

async function singleTurn() {
  const result = await ai.models.generateContent({
    model: 'gemini-3-flash-preview', // 轻量版模型，响应快
    contents: [{ parts: [{ text: '解释一下什么是ai' }] }],
  });
  // 安全获取返回文本（避免 undefined 报错）
  const candidate = result.candidates?.[0];
  const text = candidate?.content?.parts?.map(p => p.text).join('') || '';
  console.log('单轮结果：', text);
}
singleTurn();

（2）流式调用（实时返回结果）

适用于生成较长内容（如写诗、写文章），实时输出内容，避免等待：

javascript 复制代码

async function streamTurn() {
  const stream = await ai.models.generateContentStream({
    model: 'gemini-3-flash-preview',
    contents: '写一首 4 行短诗',
    // 配置生成参数：温度（随机性）、最大输出长度等
    config: { temperature: 0.9, topP: 0.9, maxOutputTokens: 300 }
  });
  // 逐块读取流式返回内容并输出
  for await (const chunk of stream) {
    const piece = chunk.candidates?.[0]?.content?.parts?.map(p => p.text || '').join('') || '';
    process.stdout.write(piece); // 实时输出，不换行
  }
  console.log('\n--- 流式完成 ---');
}
streamTurn();

（3）多轮对话（带上下文）

适用于需要上下文的连续提问，比如 "先学 Node.js 什么模块"，需维护对话历史：

php 复制代码

async function chatTurn() {
  // 存储对话历史（用户+模型的消息）
  const history = [];
  
  async function ask(prompt) {
    // 调用模型，传入历史记录+当前提问
    const result = await ai.models.generateContent({
      model: 'gemini-3-pro-preview', // 专业版模型，理解能力更强
      contents: [...history, { role: 'user', parts: [{ text: prompt }] }]
    });
    // 安全获取模型返回文本
    const candidate = result.candidates?.[0];
    const text = candidate?.content?.parts?.map(p => p.text).join('') || '';
    
    // 更新对话历史（必须存，否则下一轮无上下文）
    history.push({ role: 'user', parts: [{ text: prompt }] });
    history.push({ role: 'model', parts: [{ text: text }] });
    return text;
  }

  // 连续提问示例
  console.log('AI：', await ask('你好，我想学 Node.js'));
  console.log('AI：', await ask('先学什么模块比较好？'));
}    
chatTurn();

4. 运行代码

shell 复制代码

# 直接运行 index.js（Node 22+ 需开启 ES 模块，或改后缀为 .mjs）
node index.js
# 若报错 "Cannot use import statement outside a module"，修改 package.json 加一行：
# "type": "module",

二、关键注意事项

代理端口 ：所有代码中的 xxxx 需替换为你实际的代理端口（如 Clash 常用 7890），否则无法访问 Gemini。
模型选择：
- gemini-3-flash-preview：轻量版，响应快，适合简单提问 / 流式生成；
- gemini-3-pro-preview：专业版，理解能力强，适合多轮对话 / 复杂问题。
免费额度限制：Google 免费版有调用次数 / Token 限制，超出后需付费，建议避免高频大量调用。

错误处理：实际使用时建议加 try/catch 捕获异常（如网络问题、API Key 错误），示例：

javascript 复制代码

async function singleTurn() {
  try {
    // 原有代码
  } catch (error) {
    console.error('调用失败：', error.message);
  }
}

总结

核心前提：开启并验证代理、获取有效 GEMINI_API_KEY、配置 Node 环境和依赖；
调用方式：单轮（一次性提问）、流式（实时返回）、多轮（带上下文，需维护历史）；
关键细节：替换代理端口、选择合适模型、处理可能的异常，注意免费额度限制。