@danqiusheng/nest-nacos 1.0.0 → 1.2.0

package/README.md

@@ -1,194 +1,77 @@
-# nest-nacos 使用文档
+# @danqiusheng/nest-nacos
 
-> NestJS Nacos 插件 —— 服务发现 + 配置中心，基于 [nacos-sdk-nodejs](https://github.com/nacos-group/nacos-sdk-nodejs)，支持 gRPC 传输协议（Nacos 2.x / 3.x）。
+面向 NestJS 10/11 的 Nacos 2.x 配置中心与服务注册发现模块。
 
-**版本**：v1.0.0 | **License**：MIT
-
----
-
-## 目录
-
-1. [介绍](#1-介绍)
-2. [安装](#2-安装)
-3. [快速开始](#3-快速开始)
-4. [同步配置 forRoot](#4-同步配置-forroot)
-5. [异步配置 forRootAsync](#5-异步配置-forrootasync)
-6. [服务发现](#6-服务发现)
-7. [配置中心](#7-配置中心)
-8. [装饰器](#8-装饰器)
-9. [健康检查](#9-健康检查)
-10. [API: NacosNamingService](#10-api-nacosnamingservice)
-11. [API: NacosConfigService](#11-api-nacosconfigservice)
-12. [配置项参考](#12-配置项参考)
-13. [常见问题](#13-常见问题)
-
----
-
-## 1. 介绍
-
-**nest-nacos** 是一个 NestJS 插件，封装了 `nacos-sdk-nodejs`，为 NestJS 应用提供 **服务发现** 和 **配置中心** 能力。基于 gRPC 传输协议，支持 Nacos 2.x / 3.x 服务端。
-
-### 特性
-
-| 特性 | 说明 |
-|------|------|
-| 动态模块 | 支持 `forRoot` / `forRootAsync`，可配合 `@nestjs/config` 从环境变量读取配置 |
-| 自动注册 | 模块初始化时自动注册服务实例，销毁时自动注销，无需手动管理生命周期 |
-| 配置热更新 | 订阅配置变更，服务端实时推送，内置本地缓存与 JSON 解析 |
-| gRPC 传输 | 默认使用 gRPC，服务端实时推送，无需 UDP 端口，支持自动重连 |
-| 装饰器注入 | 提供 `@InjectNacosNaming` / `@InjectNacosConfig` 装饰器，简化依赖注入 |
-| 健康检查 | 内置 `NacosHealthIndicator`，可对接 `@nestjs/terminus` 暴露健康端点 |
-
-### 兼容性
-
-| nest-nacos | nacos-sdk-nodejs | Nacos Server | 传输协议 |
-|---|---|---|---|
-| 1.x | 2.6.x | 3.x / 2.x | gRPC（默认）/ HTTP（仅 2.x） |
-
----
-
-## 2. 安装
-
-### 步骤 1：安装 nest-nacos 和 nacos SDK
-
-```bash
-# 使用 npm
-npm install nest-nacos nacos
-
-# 使用 yarn
-yarn add nest-nacos nacos
-
-# 使用 pnpm
-pnpm add nest-nacos nacos
-```
-
-### 步骤 2：确保宿主依赖已安装
-
-以下包是 peerDependencies，通常 NestJS 项目中已存在：
+## 1. 安装
 
 ```bash
-npm install @nestjs/common @nestjs/core reflect-metadata rxjs
+npm install @danqiusheng/nest-nacos nacos
 ```
 
-### 步骤 3：（可选）安装配置模块
+## 2. 最简接入
 
-如果需要从 `.env` 文件读取 Nacos 配置，安装 `@nestjs/config`：
+未开启 Nacos 鉴权时，只需要一个地址：
 
-```bash
-npm install @nestjs/config
-```
-
-> **提示**：Nacos Server 版本选择：如果使用 Nacos 3.x，必须使用 gRPC 传输（默认）。HTTP 传输仅支持 Nacos 2.x。
-
----
-
-## 3. 快速开始
-
-以下是一个最小可用示例，展示如何在 `AppModule` 中同时启用服务发现和配置中心：
-
-```typescript
+```ts
 import { Module } from '@nestjs/common';
-import { NacosModule } from 'nest-nacos';
+import { NacosModule } from '@danqiusheng/nest-nacos';
 
 @Module({
-  imports: [
-    NacosModule.forRoot({
-      naming: {
-        serverList: '127.0.0.1:8848',
-        username: 'nacos',
-        password: 'nacos',
-      },
-      config: {
-        serverAddr: '127.0.0.1:8848',
-      },
-      instances: [
-        { serviceName: 'order-service', ip: '192.168.1.100', port: 3000 },
-      ],
-    }),
-  ],
+  imports: [NacosModule.forRoot('127.0.0.1:8848')],
 })
 export class AppModule {}
 ```
 
-应用启动后，nest-nacos 会自动：
+这会同时启用配置中心和服务注册发现，默认使用：
 
-- 连接 Nacos 服务端
-- 注册 `order-service` 实例（192.168.1.100:3000）
-- 应用关闭时自动注销该实例
+| 配置 | 默认值 |
+|---|---|
+| namespace | `public` |
+| group | `DEFAULT_GROUP` |
+| transport | HTTP OpenAPI |
+| 重试次数 | 3 次（包含第一次调用） |
 
----
+开启用户名密码鉴权时，也只需要配置一次连接信息：
 
-## 4. 同步配置 forRoot
-
-适用于配置固定的场景，直接在代码中写入连接参数：
+```ts
+NacosModule.forRoot({
+  serverAddr: '127.0.0.1:8848',
+  username: 'nacos',
+  password: 'nacos',
+});
+```
 
-```typescript
-import { NacosModule } from 'nest-nacos';
+`serverAddr` 支持集群地址数组：
 
+```ts
 NacosModule.forRoot({
-  naming: {
-    serverList: '127.0.0.1:8848',
-    namespace: 'production',
-    username: 'nacos',
-    password: 'nacos',
-  },
-  config: {
-    serverAddr: '127.0.0.1:8848',
-    namespace: 'production',
-  },
-  // 启动时自动注册的实例
-  instances: [
-    {
-      serviceName: 'order-service',
-      ip: '192.168.1.100',
-      port: 3000,
-      weight: 1.0,
-      metadata: { version: '1.0.0' },
-    },
-  ],
-  // 启动时预订阅的配置项
-  subscribeConfigs: [
-    { dataId: 'database.yaml', group: 'DEFAULT_GROUP' },
-    { dataId: 'redis.yaml', group: 'DEFAULT_GROUP' },
-  ],
-})
+  serverAddr: ['10.0.0.11:8848', '10.0.0.12:8848'],
+  namespace: 'production',
+  username: process.env.NACOS_USERNAME,
+  password: process.env.NACOS_PASSWORD,
+  ssl: false,
+});
 ```
 
----
-
-## 5. 异步配置 forRootAsync
+## 3. 使用环境变量
 
-适用于生产环境，配合 `@nestjs/config` 从环境变量或配置文件读取参数：
+插件不会隐式读取环境变量。推荐使用 Nest `ConfigModule` 明确传入配置：
 
-```typescript
+```ts
 import { Module } from '@nestjs/common';
 import { ConfigModule, ConfigService } from '@nestjs/config';
-import { NacosModule } from 'nest-nacos';
+import { NacosModule } from '@danqiusheng/nest-nacos';
 
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
     NacosModule.forRootAsync({
-      imports: [ConfigModule],
       inject: [ConfigService],
       useFactory: (config: ConfigService) => ({
-        naming: {
-          serverList: config.get('NACOS_SERVER_ADDR'),
-          namespace: config.get('NACOS_NAMESPACE'),
-          username: config.get('NACOS_USERNAME'),
-          password: config.get('NACOS_PASSWORD'),
-        },
-        config: {
-          serverAddr: config.get('NACOS_SERVER_ADDR'),
-          namespace: config.get('NACOS_NAMESPACE'),
-        },
-        instances: [
-          {
-            serviceName: config.get('SERVICE_NAME'),
-            ip: config.get('SERVICE_IP'),
-            port: config.get<number>('SERVICE_PORT'),
-          },
-        ],
+        serverAddr: config.getOrThrow<string>('NACOS_SERVER_ADDR'),
+        namespace: config.get<string>('NACOS_NAMESPACE') ?? 'public',
+        username: config.get<string>('NACOS_USERNAME'),
+        password: config.get<string>('NACOS_PASSWORD'),
       }),
     }),
   ],
@@ -196,314 +79,399 @@ import { NacosModule } from 'nest-nacos';
 export class AppModule {}
 ```
 
-对应的 `.env` 文件：
+`.env` 示例：
 
-```env
+```dotenv
 NACOS_SERVER_ADDR=127.0.0.1:8848
 NACOS_NAMESPACE=public
 NACOS_USERNAME=nacos
 NACOS_PASSWORD=nacos
-SERVICE_NAME=order-service
-SERVICE_IP=192.168.1.100
-SERVICE_PORT=3000
 ```
 
-> **说明**：`forRootAsync` 还支持 `useClass` 和 `useExisting` 两种方式，适合需要从远程配置中心或数据库读取 Nacos 连接参数的场景。
+`forRootAsync` 同时支持 `useFactory`、`useClass` 和 `useExisting`。
 
----
+## 4. 自动注册当前服务
 
-## 6. 服务发现
+在模块配置中加入 `instances`，应用启动时自动注册，关闭时自动注销：
 
-注入 `NacosNamingService` 即可使用服务注册与发现功能：
+```ts
+NacosModule.forRoot({
+  serverAddr: '127.0.0.1:8848',
+  instances: [
+    {
+      serviceName: 'order-service',
+      ip: '192.168.1.20',
+      port: 3000,
+      weight: 1,
+      ephemeral: true,
+      metadata: { env: 'prod', version: '1.2.0' },
+    },
+  ],
+});
+```
 
-```typescript
-import { Injectable, OnModuleInit } from '@nestjs/common';
-import { NacosNamingService, InjectNacosNaming } from 'nest-nacos';
+如果 IP 或端口来自环境变量，应使用 `forRootAsync` 构造 `instances`。
 
-@Injectable()
-export class RpcService implements OnModuleInit {
-  @InjectNacosNaming()
-  private readonly naming: NacosNamingService;
-
-  async onModuleInit() {
-    // 订阅 user-service 实例变更（服务端推送）
-    this.naming.subscribe('user-service', (hosts) => {
-      console.log(`user-service 实例数: ${hosts.length}`);
-    });
-  }
+## 5. 服务注册与发现
 
-  // 查询健康实例并调用
-  async callUserService() {
-    const instances = await this.naming.selectInstances('user-service');
-    if (instances.length === 0) {
-      throw new Error('user-service 无可用实例');
-    }
-    const target = instances[0];
-    return `http://${target.ip}:${target.port}`;
-  }
+### 注入服务
 
-  // 运行时动态注册新实例
-  async registerTemp() {
-    await this.naming.register({
-      serviceName: 'temp-service',
-      ip: '10.0.0.5',
-      port: 8080,
-      ephemeral: true,
-    });
-  }
+```ts
+import { Injectable } from '@nestjs/common';
+import {
+  InjectNacosNaming,
+  NacosNamingService,
+} from '@danqiusheng/nest-nacos';
+
+@Injectable()
+export class ServiceDiscovery {
+  constructor(
+    @InjectNacosNaming()
+    private readonly naming: NacosNamingService,
+  ) {}
 }
 ```
 
----
+也可以直接使用构造器注入 `NacosNamingService`。
 
-## 7. 配置中心
+### 手动注册和注销
 
-注入 `NacosConfigService` 即可读取和订阅配置：
+```ts
+const instance = {
+  serviceName: 'payment-service',
+  ip: '192.168.1.30',
+  port: 3000,
+  metadata: { env: 'prod' },
+};
 
-```typescript
-import { Injectable, OnModuleInit } from '@nestjs/common';
-import { NacosConfigService, InjectNacosConfig } from 'nest-nacos';
+await this.naming.register(instance);
+await this.naming.deregister(instance);
+```
 
-@Injectable()
-export class DbService implements OnModuleInit {
-  @InjectNacosConfig()
-  private readonly nacosConfig: NacosConfigService;
+通过插件注册的实例会被记录，Nest 模块销毁时会自动注销。
 
-  private dbConfig: any;
+### 获取健康实例
 
-  async onModuleInit() {
-    // 1. 读取配置（自动解析 JSON）
-    this.dbConfig = await this.nacosConfig.getConfigAsJson('database.yaml');
+```ts
+const instances = await this.naming.selectInstances('payment-service');
+```
 
-    // 2. 订阅配置热更新
-    this.nacosConfig.subscribe('database.yaml', 'DEFAULT_GROUP', (content) => {
-      this.dbConfig = JSON.parse(content);
-      console.log('数据库配置已热更新');
-    });
-  }
+只选择一个实例：
 
-  async updateConfig() {
-    // 发布新配置
-    await this.nacosConfig.publish(
-      'database.yaml',
-      'DEFAULT_GROUP',
-      JSON.stringify({ host: '10.0.0.1', port: 3306 }),
-    );
-  }
-}
+```ts
+const instance = await this.naming.selectInstance('payment-service', {
+  strategy: 'roundRobin',
+  metadata: { env: 'prod' },
+});
 ```
 
-> **缓存机制**：`getConfig()` 首次从 Nacos 拉取后会缓存到内存，后续调用直接返回缓存值。订阅配置变更时会自动更新缓存，无需手动管理。
+支持三种策略：
 
----
+| strategy | 行为 |
+|---|---|
+| `random` | 随机选择，默认值 |
+| `roundRobin` | 按服务轮询 |
+| `weighted` | 按 Nacos 实例权重随机选择 |
 
-## 8. 装饰器
+找不到满足健康状态和 metadata 条件的实例时，`selectInstance()` 会抛出异常。
 
-nest-nacos 提供四个装饰器简化依赖注入：
+### 订阅服务变化
 
-| 装饰器 | 注入对象 | 说明 |
-|--------|----------|------|
-| `@InjectNacosNaming()` | `NacosNamingService` | 注入封装后的 Naming 服务 |
-| `@InjectNacosConfig()` | `NacosConfigService` | 注入封装后的 Config 服务 |
-| `@InjectNacosNamingClient()` | `NacosNamingClient` | 注入原始 SDK 客户端（高级用法） |
-| `@InjectNacosConfigClient()` | `NacosConfigClient` | 注入原始 SDK 客户端（高级用法） |
+```ts
+const listener = (hosts: unknown[]) => {
+  console.log('payment-service 实例变化', hosts);
+};
 
-使用示例：
+this.naming.subscribe('payment-service', listener);
+this.naming.unSubscribe('payment-service', listener);
+
+// 不传 listener：取消该服务的全部本地订阅
+this.naming.unSubscribe('payment-service');
+```
+
+### 更新权重
+
+```ts
+await this.naming.updateWeight(instance, 0.5);
+```
 
-```typescript
+## 6. 配置中心
+
+### 注入服务
+
+```ts
 import { Injectable } from '@nestjs/common';
 import {
-  NacosNamingService,
-  NacosConfigService,
-  InjectNacosNaming,
   InjectNacosConfig,
-} from 'nest-nacos';
+  NacosConfigService,
+} from '@danqiusheng/nest-nacos';
 
 @Injectable()
-export class MyService {
-  @InjectNacosNaming()
-  private readonly naming: NacosNamingService;
-
-  @InjectNacosConfig()
-  private readonly config: NacosConfigService;
-
-  // 也可以用构造函数注入
+export class SettingsService {
   constructor(
-    private readonly naming2: NacosNamingService,
-    private readonly config2: NacosConfigService,
+    @InjectNacosConfig()
+    private readonly nacos: NacosConfigService,
   ) {}
 }
 ```
 
----
+### 读取配置
+
+```ts
+const raw = await this.nacos.getConfig('application.yaml');
+
+const config = await this.nacos.getParsedConfig<{
+  server: { port: number };
+}>('application.yaml');
+```
+
+格式默认根据 `dataId` 后缀自动识别：
+
+| 后缀/format | 返回值 |
+|---|---|
+| `.json` / `json` | JSON 对象或数组 |
+| `.yaml`、`.yml` / `yaml` | YAML 解析结果 |
+| `.properties` / `properties` | 键值对象 |
+| 其他 / `txt` | 原始字符串 |
+
+强制按 JSON 解析：
+
+```ts
+const config = await this.nacos.getConfigAsJson<AppConfig>(
+  'application.json',
+);
+```
+
+### 发布和删除配置
+
+```ts
+const published = await this.nacos.publish(
+  'application.json',
+  'DEFAULT_GROUP',
+  JSON.stringify({ featureEnabled: true }),
+);
+
+const removed = await this.nacos.remove(
+  'application.json',
+  'DEFAULT_GROUP',
+);
+```
+
+返回值为 Nacos SDK 的最终布尔结果。public namespace 删除已处理 `tenant=public` 导致的假成功问题。
+
+### 订阅热更新
+
+```ts
+const listener = (raw: string, parsed?: unknown) => {
+  console.log('配置已更新', parsed);
+};
+
+this.nacos.subscribe(
+  'application.yaml',
+  'DEFAULT_GROUP',
+  listener,
+);
+
+this.nacos.unSubscribe(
+  'application.yaml',
+  'DEFAULT_GROUP',
+  listener,
+);
+```
+
+同一个 `dataId + group` 只建立一个底层 SDK 订阅，多个业务 listener 不会导致重复回调。
+
+## 7. 启动时预加载配置
+
+```ts
+NacosModule.forRoot({
+  serverAddr: '127.0.0.1:8848',
+  subscribeConfigs: [
+    { dataId: 'application.yaml', format: 'yaml' },
+    { dataId: 'database.properties', format: 'properties' },
+    {
+      dataId: 'optional.json',
+      required: false,
+      subscribe: false,
+    },
+  ],
+});
+```
+
+默认行为：
+
+- group 为 `DEFAULT_GROUP`。
+- format 为 `auto`。
+- `subscribe: true`，预加载后继续监听热更新。
+- `required: true`，读取失败会按启动失败策略处理。
+
+合并所有已声明配置：
+
+```ts
+const merged = await this.nacos.getMergedConfig<AppConfig>();
+```
+
+对象会按声明顺序深度合并，后面的配置覆盖前面的同名字段。
+
+## 8. 本地缓存和启动失败策略
+
+```ts
+NacosModule.forRoot({
+  serverAddr: '127.0.0.1:8848',
+  subscribeConfigs: [{ dataId: 'application.yaml' }],
+  configLoading: {
+    failureMode: 'fallback',
+    cacheDir: '.nacos-cache',
+    retry: {
+      attempts: 3,
+      delayMs: 300,
+      backoffFactor: 2,
+      maxDelayMs: 3000,
+    },
+  },
+});
+```
+
+| failureMode | 行为 |
+|---|---|
+| `throw` | 读取必需配置失败时阻止应用启动，默认值 |
+| `fallback` | 优先读取本地缓存；无缓存且配置必需时阻止启动 |
+| `continue` | 记录警告并继续启动 |
+
+成功从 Nacos 读取配置后，插件会原子更新缓存文件。缓存目录应加入部署持久化目录，不建议提交到 Git。
 
 ## 9. 健康检查
 
-内置 `NacosHealthIndicator` 可对接 `@nestjs/terminus`：
+`getServerStatus()` 和 `isHealthy()` 都是异步方法：
+
+```ts
+const status = await this.naming.getServerStatus(); // UP | DOWN
+```
+
+可直接提供 Nest HTTP 健康接口：
 
-```typescript
+```ts
 import { Controller, Get } from '@nestjs/common';
-import { HealthCheckService } from '@nestjs/terminus';
-import { NacosHealthIndicator } from 'nest-nacos';
+import { NacosHealthIndicator } from '@danqiusheng/nest-nacos';
 
-@Controller('health')
-export class HealthController {
-  constructor(
-    private health: HealthCheckService,
-    private nacos: NacosHealthIndicator,
-  ) {}
+@Controller('health/nacos')
+export class NacosHealthController {
+  constructor(private readonly health: NacosHealthIndicator) {}
 
   @Get()
   check() {
-    return this.health.check([
-      () => this.nacos.isHealthy(),
-    ]);
+    return this.health.isHealthy();
   }
 }
 ```
 
-如果未安装 `@nestjs/terminus`，也可直接调用 `isHealthy()` 方法，返回 `{ status: 'up' | 'down' }`。
+返回：
 
----
+```json
+{ "status": "up" }
+```
 
-## 10. API: NacosNamingService
+## 10. 高级连接配置
 
-| 方法 | 参数 | 返回值 | 说明 |
-|------|------|--------|------|
-| `register(inst)` | `NacosInstanceOptions` | `Promise<void>` | 注册服务实例 |
-| `deregister(inst)` | `NacosInstanceOptions` | `Promise<void>` | 注销服务实例 |
-| `getAllInstances(serviceName, groupName?, clusters?, subscribe?)` | `string, ...` | `Promise<Host[]>` | 查询所有实例 |
-| `selectInstances(serviceName, groupName?, clusters?, healthy?, subscribe?)` | `string, ...` | `Promise<Host[]>` | 查询健康实例 |
-| `subscribe(info, listener)` | `string \| SubscribeInfo, Function` | `void` | 订阅实例变更推送 |
-| `unSubscribe(info, listener?)` | `string \| SubscribeInfo, Function?` | `void` | 取消订阅 |
-| `getServerStatus()` | 无 | `'UP' \| 'DOWN'` | 获取服务端状态 |
-| `getRawClient()` | 无 | `NacosNamingClient \| null` | 获取原始 SDK 客户端 |
+绝大多数项目只需要顶层共享配置。只有 Naming 和 Config 使用不同地址、命名空间或云鉴权参数时，才使用嵌套配置：
 
-### subscribe 参数说明
+```ts
+NacosModule.forRoot({
+  serverAddr: 'shared-nacos:8848',
+  username: 'shared-user',
+  password: 'shared-password',
+
+  naming: {
+    serverList: 'naming-nacos:8848',
+    namespace: 'service-space',
+    appName: 'order-service',
+  },
+  config: {
+    serverAddr: 'config-nacos:8848',
+    namespace: 'config-space',
+    accessKey: process.env.NACOS_ACCESS_KEY,
+    secretKey: process.env.NACOS_SECRET_KEY,
+  },
+});
+```
 
-`info` 参数支持两种形式：
+嵌套配置优先于顶层共享配置。只配置 `naming` 或只配置 `config`，可以只启用对应能力。
 
-```typescript
-// 形式一：字符串（serviceName）
-naming.subscribe('user-service', (hosts) => { ... });
+## 11. 原始 SDK 客户端
 
-// 形式二：对象（可指定分组和集群）
-naming.subscribe(
-  { serviceName: 'user-service', groupName: 'PROD_GROUP', clusters: 'BJ' },
-  (hosts) => { ... },
-);
+只有插件服务未覆盖 SDK 能力时才建议使用：
+
+```ts
+import {
+  InjectNacosConfigClient,
+  InjectNacosNamingClient,
+} from '@danqiusheng/nest-nacos';
+import type {
+  NacosConfigClient,
+  NacosNamingClient,
+} from 'nacos';
+
+constructor(
+  @InjectNacosNamingClient()
+  private readonly namingClient: NacosNamingClient,
+  @InjectNacosConfigClient()
+  private readonly configClient: NacosConfigClient,
+) {}
 ```
 
----
-
-## 11. API: NacosConfigService
-
-| 方法 | 参数 | 返回值 | 说明 |
-|------|------|--------|------|
-| `getConfig(dataId, group?)` | `string, string?` | `Promise<string>` | 获取配置内容（带缓存） |
-| `getConfigAsJson<T>(dataId, group?)` | `string, string?` | `Promise<T>` | 获取配置并解析为 JSON |
-| `publish(dataId, group, content)` | `string, string, string` | `Promise<boolean>` | 发布配置 |
-| `remove(dataId, group)` | `string, string` | `Promise<boolean>` | 删除配置 |
-| `subscribe(dataId, group, listener)` | `string, string, Function` | `void` | 订阅配置变更推送 |
-| `unSubscribe(dataId, group, listener?)` | `string, string, Function?` | `void` | 取消订阅 |
-| `getRawClient()` | 无 | `NacosConfigClient \| null` | 获取原始 SDK 客户端 |
-
-> **默认 group**：`getConfig()` 和 `getConfigAsJson()` 的 `group` 参数默认值为 `'DEFAULT_GROUP'`，如果配置在默认分组下可省略。
-
----
-
-## 12. 配置项参考
-
-### NacosModuleOptions
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `naming` | `NacosNamingOptions` | 否 | Naming 服务发现配置，不传则不启用 |
-| `config` | `NacosConfigOptions` | 否 | Config 配置中心配置，不传则不启用 |
-| `instances` | `NacosInstanceOptions[]` | 否 | 启动时自动注册的服务实例列表 |
-| `subscribeConfigs` | `{ dataId, group }[]` | 否 | 启动时预订阅的配置项列表 |
-
-### NacosNamingOptions
-
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `serverList` | `string \| string[]` | - | Nacos 服务端地址 |
-| `namespace` | `string` | `'public'` | 命名空间 ID |
-| `transport` | `'grpc' \| 'http'` | `'grpc'` | 传输协议 |
-| `username` | `string` | - | 用户名 |
-| `password` | `string` | - | 密码 |
-| `ssl` | `boolean` | `false` | 是否启用 TLS/SSL |
-| `ak` | `string` | - | 阿里云 RAM AccessKey |
-| `sk` | `string` | - | 阿里云 RAM SecretKey |
-| `appName` | `string` | - | 应用名 |
-
-### NacosConfigOptions
-
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `serverAddr` | `string \| string[]` | - | Nacos 服务端地址 |
-| `namespace` | `string` | `'public'` | 命名空间 ID |
-| `transport` | `'grpc' \| 'http'` | `'grpc'` | 传输协议 |
-| `username` | `string` | - | 用户名 |
-| `password` | `string` | - | 密码 |
-| `ssl` | `boolean` | `false` | 是否启用 TLS/SSL |
-| `accessKey` | `string` | - | 阿里云 RAM AccessKey |
-| `secretKey` | `string` | - | 阿里云 RAM SecretKey |
-| `signatureRegionId` | `string` | - | v4 签名区域 ID |
-
-### NacosInstanceOptions
-
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `serviceName` | `string` | - | 服务名 |
-| `ip` | `string` | - | 实例 IP |
-| `port` | `number` | - | 实例端口 |
-| `weight` | `number` | `1.0` | 权重 |
-| `ephemeral` | `boolean` | `true` | 是否临时实例 |
-| `clusterName` | `string` | - | 集群名 |
-| `groupName` | `string` | `'DEFAULT_GROUP'` | 分组名 |
-| `metadata` | `Record<string, string>` | - | 元数据 |
-
----
+原始客户端由模块统一关闭，不要在业务代码中重复调用 `close()`。
+
+## 12. 兼容性
+
+| 组件 | 支持范围 |
+|---|---|
+| NestJS | 10.x、11.x |
+| Node.js | >= 16 |
+| Nacos Node SDK | `nacos` 2.6.x |
+| Nacos Server | 2.x（已对 2.5.3 做真实端到端验证） |
+| Nacos Server 3.x | 不支持 |
+| 传输协议 | Nacos HTTP OpenAPI；不支持 gRPC |
+
+`nacos@2.6.x` 没有实现 Nacos 3.x 所需的 gRPC 协议。配置 `transport: 'grpc'` 时插件会立即抛出错误，不会静默回退造成假成功。
+
+插件本身不需要 Java。只有在本机运行 Nacos Server 时才需要 Java；NestJS 应用连接远程 Nacos 时只需要 Node.js。
 
 ## 13. 常见问题
 
-### 只启用配置中心，不启用服务发现可以吗？
+### `getServerStatus()` 类型是 Promise
 
-可以。`naming` 和 `config` 都是可选的，只传 `config` 即可：
+必须使用 `await`：
 
-```typescript
-NacosModule.forRoot({
-  config: { serverAddr: '127.0.0.1:8848' },
-  // 不传 naming，NacosNamingService 注入后客户端为 null
-})
+```ts
+const status = await this.naming.getServerStatus();
 ```
 
-此时 `NacosNamingService` 仍可注入，但调用其方法会抛出 `NacosNamingClient 未初始化` 错误。
+### 鉴权后 Naming 正常但 Config 失败
 
-### 如何选择 gRPC 还是 HTTP 传输？
+使用顶层 `username/password` 可以同时传给两个客户端，避免重复配置遗漏：
 
-| 传输协议 | Nacos 2.x | Nacos 3.x | 推荐场景 |
-|----------|-----------|-----------|----------|
-| `grpc`（默认） | 支持 | 支持 | 推荐，实时推送，无需 UDP |
-| `http` | 支持 | 不支持 | 仅兼容旧版 Nacos 2.x 时使用 |
+```ts
+NacosModule.forRoot({ serverAddr, username, password });
+```
 
-### Nacos 3.x 连接失败怎么办？
+### public namespace 应该怎么写
 
-Nacos 3.x 已移除 HTTP API 支持，必须使用 gRPC 传输（默认）。确保：
+省略 `namespace` 或设置为 `public` 都可以。插件会按 Naming 和 Config SDK 的不同要求正确归一化。
 
-- 未设置 `transport: 'http'`
-- Nacos Server 的 gRPC 端口（默认 9848，即 serverPort + 1000）已开放
-- 检查用户名密码是否正确
+### 应用无法退出
 
-### 配置更新后业务代码没有生效？
+请通过 Nest 的 `app.close()` 或正常进程信号关闭。模块销毁时会注销实例、取消订阅并关闭两个 SDK 客户端。
 
-确保通过 `subscribe()` 订阅了配置变更，并在回调中更新本地变量。`getConfig()` 返回的是缓存值，订阅后缓存会自动更新，但业务代码中引用的变量需要手动更新。
+### Nacos 3.x 为什么不能连接
 
-### 如何获取原始 SDK 客户端？
+当前 Node SDK 没有 Nacos 3.x gRPC 实现。需要 Nacos 3.x 时不能通过修改 `transport` 参数解决，应等待或替换真正支持该协议的 SDK。
 
-使用 `getRawClient()` 方法或 `@InjectNacosNamingClient()` / `@InjectNacosConfigClient()` 装饰器获取原始 `NacosNamingClient` / `NacosConfigClient` 实例，调用 SDK 未封装的高级 API。
+## 14. 验证
 
----
+```bash
+npm ci
+npm run build
+npm test
+```
 
-*nest-nacos v1.0.0 · MIT License · 基于 nacos-sdk-nodejs v2.6.x*
+发布前还应针对真实 Nacos 2.x 执行端到端测试，并从服务端接口反查注册、配置发布和删除结果。