# @google-cloud/cloud-sql-connector 中文文档

规范地址：https://npmcn.com/package/%40google-cloud/cloud-sql-connector/

版本：1\.13\.0
npm 元数据更新时间：2026-11-11T22:32:07.689Z
中文译文更新时间：2026-11-16T19:33:50.296Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40google-cloud/cloud-sql-connector
原文对照：https://npmcn.com/package/%40google-cloud/cloud-sql-connector/?lang=original
项目主页：https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector#readme
源码仓库：https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：444 kB，149 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2023-03-14T20:34:58.288Z
- 最新版本发布：2026-11-11T22:32:07.504Z
- 近 30 天下载量：22238837（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 12 个）

## 中文简介

一个安全连接到您的 Cloud SQL 实例的 JavaScript 库

## 安装

```sh
npm install @google-cloud/cloud-sql-connector
```

也可以使用：`pnpm add @google-cloud/cloud-sql-connector`、`yarn add @google-cloud/cloud-sql-connector`、`bun add @google-cloud/cloud-sql-connector`

## README

[![cloud-sql-nodejs-connector image](https://raw.githubusercontent.com/GoogleCloudPlatform/cloud-sql-nodejs-connector/main/docs/images/cloud-sql-nodejs-connector.png)](https://www.npmjs.com/package/@google-cloud/cloud-sql-connector)

# 云 SQL 节点.js 连接器

[![CI](https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector/actions/workflows/tests.yml/badge.svg?event=push)](https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector/actions/workflows/tests.yml?query=event%3Apush+branch%3Amain) [![npm](https://img.shields.io/npm/v/@google-cloud/cloud-sql-connector)](https://www.npmjs.com/package/@google-cloud/cloud-sql-connector) [![npm](https://img.shields.io/npm/dm/@google-cloud/cloud-sql-connector)](https://www.npmjs.com/package/@google-cloud/cloud-sql-connector)

这个 **云 SQL 节点.js 连接器** 是 Cloud SQL 连接器, 设计用于 与节点.js运行时间。 使用 Cloud SQL 连接器提供本地 备选案文 [云 SQL Auth 代理服务器](https://cloud.google.com/sql/docs/mysql/sql-proxy) 提供以下福利:

-   **IAM 授权 :** 使用 IAM 权限来控制谁可以连接到 您的 Cloud SQL 实例
-   **改进安保:** 使用坚固,更新的TLS 1.3加密(包括 自动 [混合后量子键交换](https://npmcn.com/package/%40google-cloud/cloud-sql-connector/#readme-post-quantum-cryptography-pqc) openSSL 3.5+运行时间,如节点22.20+和24.5+)和身份 在客户端连接器和服务器端代理机之间进行校验, 独立于数据库协议.
-   **方便时间:** 删除使用和分发SSL的要求 证书,以及管理防火墙或源/指定IP地址.
-   (可选) **IAM DB 认证 :** 向 [Cloud SQL 的自动 IAM DB AuthN](https://cloud.google.com/sql/docs/postgres/authentication) 特性.

Cloud SQL 节点.js 连接器是一个要和数据库一起使用的软件包 驾驶员。 目前支持的驱动程序有:

-   [`pg`](https://www.npmjs.com/package/pg) (PostgreSQL) (英语)
-   [`mysql2`](https://www.npmjs.com/package/mysql2) (MySQL) (英语)
-   [`tedious`](https://www.npmjs.com/package/tedious) (SQL 服务器)

## 安装

您可以使用 `npm install`数字 :

```sh
npm install @google-cloud/cloud-sql-connector
```

### APIs和服务

此库需要以下内容才能成功创建 Cloud SQL 连接 :

-   IAM 主要(用户、服务账户等) [云 SQL 客户端](https://cloud.google.com/sql/docs/mysql/roles-and-permissions) 角色。 。 。 这个IAM本金将用于 [全权证书](https://npmcn.com/package/%40google-cloud/cloud-sql-connector/#readme-credentials)。 。 。 .
-   这个 [云 SQL 管理员 API](https://console.cloud.google.com/apis/api/sqladmin.googleapis.com) 在您的 Google 云中启用 项目。 默认情况下, API 将被调用到与 学校校长.

### 全权证书

此库使用 [应用程序默认证书( ADC)](https://cloud.google.com/docs/authentication#adc) 战略 解决全权证书问题。 请看 [这些如何设置 ADC 的指令](https://cloud.google.com/docs/authentication/provide-credentials-adc) (Google Cloud 应用程序 vs 本地开发, IAM 用户 vs 服务账户证书), 或咨询 [节点.js google-auth-library (英语)](https://cloud.google.com/nodejs/docs/reference/google-auth-library/latest#ways-to-authenticate)。 。 。 .

## 使用量

连接器包意在与数据库驱动程序并用,在 在示例之后, 您可以看到如何创建新连接符并获得有效性 选项,然后可以在启动新连接时使用.

更多例子请检查 [`examples/`](https://npmcn.com/package/%40google-cloud/cloud-sql-connector/examples/) 文件夹.

### 使用 PostgreSQL

这是怎样开始一个新的 [`pg`](https://www.npmjs.com/package/pg) 连接池.

```js
import pg from 'pg';
import {Connector} from '@google-cloud/cloud-sql-connector';
const {Pool} = pg;

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PUBLIC',
});
const pool = new Pool({
  ...clientOpts,
  user: 'my-user',
  password: 'my-password',
  database: 'db-name',
  max: 5,
});
const {rows} = await pool.query('SELECT NOW()');
console.table(rows); // prints returned time value from server

await pool.end();
connector.close();
```

### 使用 MySQL

这是怎样开始一个新的 [`mysql2`](https://www.npmjs.com/package/mysql2) 连接池.

```js
import mysql from 'mysql2/promise';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PUBLIC',
});
const pool = await mysql.createPool({
  ...clientOpts,
  user: 'my-user',
  password: 'my-password',
  database: 'db-name',
});
const conn = await pool.getConnection();
const [result] = await conn.query(`SELECT NOW();`);
console.table(result); // prints returned time value from server

await pool.end();
connector.close();
```

### 使用 SQL 服务器

这是怎样开始一个新的 [`tedious`](https://www.npmjs.com/package/tedious) 连接.

```js
const {Connection, Request} = require('tedious');
const {Connector} = require('@google-cloud/cloud-sql-connector');

const connector = new Connector();
const clientOpts = await connector.getTediousOptions({
  instanceConnectionName: process.env.SQLSERVER_CONNECTION_NAME,
  ipType: 'PUBLIC',
});
const connection = new Connection({
  // Please note that the `server` property here is not used and is only defined
  // due to a bug in the tedious driver (ref: https://github.com/tediousjs/tedious/issues/1541)
  // With that in mind, do not try to change this value since it will have no
  // impact in how the connector works, this README will be updated to remove
  // this property declaration as soon as the tedious driver bug is fixed
  server: '0.0.0.0',
  authentication: {
    type: 'default',
    options: {
      userName: 'my-user',
      password: 'my-password',
    },
  },
  options: {
    ...clientOpts,
    // Please note that the `port` property here is not used and is only defined
    // due to a bug in the tedious driver (ref: https://github.com/tediousjs/tedious/issues/1541)
    // With that in mind, do not try to change this value since it will have no
    // impact in how the connector works, this README will be updated to remove
    // this property declaration as soon as the tedious driver bug is fixed
    port: 9999,
    database: 'my-database',
  },
});

connection.connect(err => {
  if (err) {
    throw err;
  }
  let result;
  const req = new Request('SELECT GETUTCDATE()', err => {
    if (err) {
      throw err;
    }
  });
  req.on('error', err => {
    throw err;
  });
  req.on('row', columns => {
    result = columns;
  });
  req.on('requestCompleted', () => {
    console.table(result);
  });
  connection.execSql(req);
});

connection.close();
connector.close();
```

### 使用本地代理隧道( Unix 域套接字)

使用 Cloud SQL 节点的另一种可能方法是创建一个 已建立连接的隧道本地代理服务器 使用 `Connector.startLocalProxy()` 方法代替 `Connector.getOptions()`。 。 。 .

> \[注\]
> 
> 这个 `startLocalProxy()` 目前只支持 MySQL 和 PostgreSQL 的方法 因为它使用目前SQL Server不支持的 Unix 域套接字 .

此替代方法允许使用连接器库 不支持的驱动程序, 如 [普里斯马](https://www.prisma.io/)这里有一个 如何使用 PostgreSQL 驱动程序的例子 :

```js
import {Connector} from '@google-cloud/cloud-sql-connector';
import {PrismaClient} from '@prisma/client';

const connector = new Connector();
await connector.startLocalProxy({
  instanceConnectionName: 'my-project:us-east1:my-instance',
  listenOptions: { path: '.s.PGSQL.5432' },
});
const hostPath = process.cwd();

const datasourceUrl =
 `postgresql://my-user:password@localhost/dbName?host=${hostPath}`;
const prisma = new PrismaClient({ datasourceUrl });

connector.close();
await prisma.$disconnect();
```

关于每个被支持的Cloud SQL数据库中的实例,请参考我们 [Prisma 样本](https://npmcn.com/package/%40google-cloud/cloud-sql-connector/examples/README.md#prisma)。 。 。 .

### 指定 IP 地址类型

用于节点.js的 Cloud SQL 连接器可用于连接 Cloud SQL 使用公共和私人IP地址以及 [私人服务连接](https://cloud.google.com/vpc/docs/private-service-connect) (中文(简体) ). 指定要连接的 IP 地址类型 `getOptions` 通过 `ipType` 参数.

默认情况下, 连接将被配置到 `'PUBLIC'` 连接到 公共IP,用来配置连接,以使用实例的私人IP, 使用情况 `'PRIVATE'` 页:1 `ipType` 内容如下:

**说明:** 如果指定私人IP或私人服务连接, 您的应用程序 必须附在适当的 VPC 网络上才能连接到您的 Cloud SQL 举个例子 对于大多数应用来说,这将需要使用 [VPC 连接器](https://cloud.google.com/vpc/docs/configure-serverless-vpc-access#create-connector)。 。 。 .

#### 如何使用私人IP的例子

```js
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PRIVATE',
});
```

#### 如何使用 [私人服务连接](https://cloud.google.com/vpc/docs/private-service-connect) (PSC) IP 软件

```js
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: 'PSC',
});
```

#### 如何使用的实例 `IpAddressTypes` 类型脚本

```js
import {Connector, IpAddressTypes} from '@google-cloud/cloud-sql-connector';
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  ipType: IpAddressTypes.PSC,
});
```

### 自动 IAM 数据库认证

使用 [自动 IAM 数据库认证](https://cloud.google.com/sql/docs/postgres/authentication#automatic) 当 使用 Postgres 或 MySQL 驱动程序.

确保 [配置您的 Cloud SQL 实例以允许 IAM 认证](https://cloud.google.com/sql/docs/postgres/create-edit-iam-instances#configure-iam-db-instance) 财务报告和审定财务报表 [添加 IAM 数据库用户](https://cloud.google.com/sql/docs/postgres/create-manage-iam-users#creating-a-database-user)。 。 。 .

A 类 `Connector` 能够配置到 Cloud SQL 实例 自动 IAM 数据库认证 `getOptions` 通过 `authType` 参数.

```js
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM',
});
```

当为 IAM 认证配置连接时 `password` 参数 中可以省略 `user` 参数的格式如下:

> Postgres:对于一个IAM用户账户,这是用户的电子邮件地址. 对于一个服务账户,它是服务账户的电子邮件,没有 `.gserviceaccount.com` 域后缀.
> 
> MySQL:对于一个IAM用户账户,这是用户的电子邮件地址,没有 页:1 `@` 或域名。 举例来说 `test-user@gmail.com`,设置 `user` 字段改为 `test-user`。对于服务账户,这是服务 账户的电子邮件地址没有 `@project-id.iam.gserviceaccount.com` 后缀.

使用 `test-sa@test-project.iam.gserviceaccount.com` 要连接的服务账户见下文.

#### Postgres 自动 IAM 认证示例

```js
import pg from 'pg';
import {Connector} from '@google-cloud/cloud-sql-connector';
const {Pool} = pg;

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM',
});
const pool = new Pool({
  ...clientOpts,
  user: 'test-sa@test-project.iam',
  database: 'db-name',
  max: 5,
});
const {rows} = await pool.query('SELECT NOW()');
console.table(rows); // prints returned time value from server

await pool.end();
connector.close();
```

#### MySQL 自动 IAM 认证示例

```js
import mysql from 'mysql2/promise';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: 'IAM',
});
const pool = await mysql.createPool({
  ...clientOpts,
  user: 'test-sa',
  database: 'db-name',
});
const conn = await pool.getConnection();
const [result] = await conn.query(`SELECT NOW();`);
console.table(result); // prints returned time value from server

await pool.end();
connector.close();
```

#### 如何使用的实例 `AuthTypes` 类型脚本

对于类型脚本用户 `AuthTypes` 类型可以直接导入和使用 用于自动IAM数据库认证.

```js
import {AuthTypes, Connector} from '@google-cloud/cloud-sql-connector';
const clientOpts = await connector.getOptions({
  instanceConnectionName: 'my-project:region:my-instance',
  authType: AuthTypes.IAM,
});
```

### 量子后密码学(PQC)

Cloud SQL 节点连接器在 TLS 1. 3 上建立 mTLS 连接 (单位:千美元)`minVersion: 'TLSv1.3'`)使用Node.js的内置 `node:tls` 模块 默认曲线偏好。 当运行在包含节点的运行时 **OpenSSL 3. 5.0 或以后时间**,连接器自动提供和谈判 混合量子后密钥交换组 **`X25519MLKEM768`** (ML-KEM-768) (韩语) 与 X25519 结合,只要Cloud SQL 实例支持它. 无代码 需要更改或连接符选项.

#### 节点和 OpenSSL 运行时间要求

官方节点.js 分布静态捆绑 OpenSSL 而非链接 针对主机操作系统的OpenSSL库. 混合 `X25519MLKEM768` 键 在正式节点.js放出捆绑的框中支持交换 OpenSSL 3.5+ : (中文(简体) )

-   **节点.js 22 LTS:** `>= 22.20.0`
-   **节点.js 24 LTS:** `>= 24.5.0`
-   **节点.js 25+:** 所有释放

如果您使用自定义或 Linux 分发包装的节点.js 二进制 动态链接到系统 OpenSSL, 确保链接到的 OpenSSL 版本 `3.5.0` 或更新.

您可以检查您的节点所使用 OpenSSL 版本 :

```sh
node -p "process.versions.openssl"
```

产出 `3.5.0` 或更高(例如, `3.5.8` 或者说 `3.6.5`) 表示 `X25519MLKEM768` 键交换可用.

#### 向后兼容

混合式后量子键交换是倒相兼容的:

-   在 OpenSSL 3.5+ 运行时, `node:tls` 两种混合广告 (单位:千美元)`X25519MLKEM768`)和古典语(`X25519`, (中文(简体) ), `P-256`TLS 中的小组 1.3 国家 `ClientHello`如果一个 Cloud SQL 实例只提供古典组,则 TLS 握手自动回归古典 `X25519` (或 `P-256`(中文(简体) ) 无出错.
-   用 OpenSSL 在更古老的节点上运行的应用程序 `< 3.5.0` 继续使用经典密钥交换在TLS 1.3上连接.

#### 选择退出

禁用客户端的量子后密钥交换( 例如, 在周围工作) 拒绝较大 TLS 1. 3 的遗留网络中间框 `ClientHello` 页:1 将 TLS 握手限制在经典曲线上, 设置 `tls.DEFAULT_ECDH_CURVE` 在此之前 打开连接( 注意此更改全过程默认值 `node:tls` 未指定明示的连接 `ecdhCurve`:

```js
import tls from 'node:tls';

tls.DEFAULT_ECDH_CURVE = 'X25519:prime256v1:secp384r1';
```

或者,在不修改应用程序代码的情况下,通过设置 `NODE_OPTIONS` 环境变量(注: `NODE_OPTIONS` 也继承了 由子节点js进程进行:

```sh
export NODE_OPTIONS='--import=data:text/javascript,import%20tls%20from%20%22node:tls%22%3Btls.DEFAULT_ECDH_CURVE%3D%22X25519:prime256v1:secp384r1%22'
```

## 使用方式 `Google Auth Library: Node.js Client` 全权证书

一个可以用 [`google-auth-library`](https://github.com/googleapis/google-auth-library-nodejs/) 全权证书 使用此库时提供 `AuthClient` 或者说 `GoogleAuth` 实例 `Connector`。 。 。 .

```sh
npm install google-auth-library
```

```js
import {GoogleAuth} from 'google-auth-library';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector({
  auth: new GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/sqlservice.admin']
  }),
});
```

在配置不同于 应用程序默认证书 。 见 [文档](https://cloud.google.com/nodejs/docs/reference/google-auth-library/latest#loading-credentials-from-environment-variables) 编辑 `google-auth-library` 更多信息.

### 设定定制配额项目

习惯 **谷歌 Auth 库** `auth` 属性也可以用于设置 特定属性,如定制配额项目。 后续行动 前例中, 您可以使用自定义设置配额项目 `auth` 证书 :

```js
import {GoogleAuth} from 'google-auth-library';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector({
  auth: new GoogleAuth({
    clientOptions: {
      quotaProjectId: '<custom quota project>',
    },
  }),
});
```

## 通过环境变量的额外定制

通过环境可以改变一些库默认行为 变量。 以下简要提及所支持的价值观及其效果:

-   `GOOGLE_APPLICATION_CREDENTIALS`: 如果定义了连接符, 将使用此 文件为自定义证书文件,用于认证 Cloud SQL API。 应该 jSON 文件的路径。 你们可以 [在此找到更多关于如何获取有效证书文件的文件](https://github.com/googleapis/google-cloud-node#download-your-service-account-credentials-json-file)。 。 。 .
-   `GOOGLE_CLOUD_QUOTA_PROJECT`:曾为Cloud SQL设置自定义配额项目 API 定义时 .

## 使用高级灾后恢复和DNS域名来识别实例

连接符可以被配置到使用 DNS 查看实例 . 使用 Cloud SQL 管理的 DNS 名称 [高级灾后恢复](https://docs.cloud.google.com/sql/docs/mysql/use-advanced-disaster-recovery), (中文(简体) ), 或您管理的域名.

### 使用高级回收写出终点 DNS 名称

[高级灾后恢复](https://docs.cloud.google.com/sql/docs/mysql/use-advanced-disaster-recovery) 创建您 Cloud SQL 数据库实例的地理分布复制。 表演时 在数据库实例中切换或失效,连接器将优雅地断开 旧的初级法院 与新的初级法院重接.

执行指令 [使用写入结束点连接](https://docs.cloud.google.com/sql/docs/mysql/connect-to-instance-using-write-endpoint) 以获取您初级实例的字端点 DNS 名称。 然后,使用此写出终点 DNS 名称来配置连接符.

### 配置您的 DNS 记录

连接器可能被配置为使用您定义的 DNS .

在 Cloud SQL 实例中添加 DNS TXT 记录 **私营** DNS 服务器 或者您应用程序使用的私人 Google Cloud DNS Zone .

**说明:** 您强烈反对为您添加 DNS 记录 Cloud SQL 实例到公共 DNS 服务器. 这将允许任何人在 互联网可以发现 Cloud SQL 实例名称 .

例如:假设您想要使用域名 `prod-db.mycompany.example.com` 连接到您的数据库实例 `my-project:region:my-instance`。您将创建以下 DNS 记录 :

-   记录类型 : `TXT`
-   名称 : `prod-db.mycompany.example.com` - 这是应用程序使用的域名
-   数值 : `my-project:region:my-instance` - 这是实例名称

### 配置连接器

配置上述连接器,将连接器ID替换为 dNS名称.

调整以上 MySQL + 数据库/ sql 示例:

```js
import mysql from 'mysql2/promise';
import {Connector} from '@google-cloud/cloud-sql-connector';

const connector = new Connector();
const clientOpts = await connector.getOptions({
  domainName: 'prod-db.mycompany.example.com',
  ipType: 'PUBLIC',
});

const pool = await mysql.createPool({
  ...clientOpts,
  user: 'my-user',
  password: 'my-password',
  database: 'db-name',
});
const conn = await pool.getConnection();
const [result] = await conn.query(`SELECT NOW();`);
console.table(result); // prints returned time value from server

await pool.end();
connector.close();
```

## 使用 DNS 域名自动失效

例如:假设应用程序被配置为使用 域名 `prod-db.mycompany.example.com`最初,私人DNS 带值的区有 TXT 记录 `my-project:region:my-instance`编辑 应用程序建立连接 `my-project:region:my-instance` 云SQL实例. 使用 `domainName` 选项 :

然后重新配置应用程序以使用不同的数据库 实例,更改 `prod-db.mycompany.example.com` DNS 记录 从 `my-project:region:my-instance` 改为 `my-project:other-region:my-instance-2`

应用程序中的连接器检测此更改 DNS记录. 现在,当应用程序使用 域名 `prod-db.mycompany.example.com`,它将连接到 `my-project:other-region:my-instance-2` 云SQL实例.

连接器将自动关闭所有已有的连接到 `my-project:region:my-instance`。这将迫使连接池 建立新的连接。 此外,还可能造成数据库查询正在进行中 失败.

连接器将默认每隔30秒对 DNS 名称的更改进行投票. 您可以使用连接器配置连接频率 `failoverPeriod` 选项。 当设置为 0 时, 连接器将禁用 民意测验,并只检查DNS记录在创建新时是否有变化 连接.

## 支助政策

### 主要版本生命周期

这个项目使用 [语义版本](https://semver.org/),并使用 与支持主要版本有关的生命周期:

**活动** - 现行版本获得所有新功能和安全修正(即 否则, 新主要版本为: 保证至少"活动"1年.

**折旧** - 贬值的版本继续得到安全和关键 错误修正, 但不接受新特性 。 贬值的版本 支助一年.

**不支持** - 任何主要版本 已经贬值了1年 被视为不支持.

### 支持的节点.js版本

我们的客户端图书馆跟着 [节点.js发布时间表](https://nodejs.org/en/about/releases/)。 。 。 . 图书馆兼容所有当前 _活动_ 财务报告和审定财务报表 _维修_ 版本 节点. 如果你在使用"节点"的报废版本,我们建议你 尽快更新到一个积极支持的LTS版本.

Google 的客户端库支持在 a 上的 Node.js runtimes 的遗留版本 以下列警告为依据:

-   后遗症版本不进行连续整合测试.
-   一些安全补丁和特性不能被后移植.
-   依赖关系不能不断更新.

### 释放胆量

该项目旨在至少每月发布一次。 如果没有新的特性 或已添加修正,具有最新依赖关系的新 PATCH 版本是 释放.

## 捐款

我们欢迎外部捐助。 请看我们的 [贡献指南](https://npmcn.com/package/%40google-cloud/cloud-sql-connector/docs/contributing.md) 关于如何最好地 贡献.

## 许可证

Apache 版本 2.0

见 [自由主义](https://npmcn.com/package/%40google-cloud/cloud-sql-connector/LICENSE)

## 常见问题

### @google-cloud/cloud-sql-connector 是什么？

一个安全连接到您的 Cloud SQL 实例的 JavaScript 库

### 如何安装 @google-cloud/cloud-sql-connector？

在项目目录运行 npm install @google-cloud/cloud-sql-connector，或使用 pnpm add / yarn add / bun add。

### @google-cloud/cloud-sql-connector 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @google-cloud/cloud-sql-connector 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @google-cloud/cloud-sql-connector 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @google-cloud/cloud-sql-connector 可以商用吗？

@google-cloud/cloud-sql-connector 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @google-cloud/cloud-sql-connector 的下载量有多少？

根据 npm 官方下载统计，@google-cloud/cloud-sql-connector 在 2026/10/17 – 2026/11/15 这 30 天内被下载 22,238,837 次，日均约 741,295 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @google-cloud/cloud-sql-connector 还在维护吗？

最新版本 1\.13\.0 发布于 2026/11/12（4 天前）；至今共发布 44 个版本，其中过去 12 个月发布了 12 个；首次发布于 2023/03/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

