# @countrystatecity/countries-browser 中文文档

规范地址：https://npmcn.com/package/%40countrystatecity/countries-browser/

版本：3\.0\.1
npm 元数据更新时间：2026-11-03T14:19:12.956Z
中文译文更新时间：2026-11-10T20:46:56.686Z
软件包许可：ODbL-1\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40countrystatecity/countries-browser
原文对照：https://npmcn.com/package/%40countrystatecity/countries-browser/?lang=original
项目主页：https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/countries-browser#readme
源码仓库：https://github.com/dr5hn/countrystatecity-npm

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

- 包体积（解压后）：65.7 MB，5248 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-03-28T09:09:04.703Z
- 最新版本发布：2026-11-03T14:19:12.555Z
- 近 30 天下载量：42825（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

有 jsDelivr CDN 和懒惰加载的浏览器本土国家、州和城市数据

## 安装

```sh
npm install @countrystatecity/countries-browser
```

也可以使用：`pnpm add @countrystatecity/countries-browser`、`yarn add @countrystatecity/countries-browser`、`bun add @countrystatecity/countries-browser`

## README

# @ 国家状态/ 国家浏览器

[![npm](https://img.shields.io/npm/v/@countrystatecity/countries-browser)](https://www.npmjs.com/package/@countrystatecity/countries-browser) [![CI](https://github.com/dr5hn/countrystatecity-npm/workflows/Pipeline/badge.svg)](https://github.com/dr5hn/countrystatecity-npm/actions/workflows/ci.yml) [![npm downloads](https://img.shields.io/npm/dm/@countrystatecity/countries-browser?label=countries-browser)](https://www.npmjs.com/package/@countrystatecity/countries-browser) [![npm downloads](https://img.shields.io/npm/dw/@countrystatecity/countries-browser?label=countries-browser)](https://www.npmjs.com/package/@countrystatecity/countries-browser)

有jsDelivr CDN和懒惰加载的浏览器本地国家、州和城市数据。 与服务器软件包相同的API——在React,Vue,Svelte,Vite,以及任何浏览器环境中工作.

**环境:** 🌐 **浏览器本地** (反应, Vue, Svelte, Vite, 以及任何浏览器环境)

## 升级到 3. 0

此版本使用 **v5.2.0-出口**。审查 [上游 v5 迁移说明](https://github.com/dr5hn/countries-states-cities-database/releases/tag/v5.0.0) 在更新所储存的身份证之前:一些记录被退役或被修复。 城市状态链接现在可以无效 。 全国城市装载机包括这些记录。 保留供应 `NOTICE-*.txt` 带有重新分配数据的文件。 见 [软件包迁移指南](https://github.com/dr5hn/countrystatecity-npm/blob/main/MIGRATING-V5.md)。 。 。 .

## 较早的移徙: 2.0.0

现在的数据来自上游 **v 4.0出口.50**. v3.2 → v 4.0 过渡取消了4,486个城市标识(重复,美国各县迁移到一个单独的县数据集,不设地),将7,527个城市重新分配到不同的州,在退休时又增加了27个州. 存储的ID和每个州的结果都可以改变;美国县不再作为城市返回. 后来的导出更正包含在本快照中.

在升级存储的城市/州编号之前, 使用 [`removed_ids_v3.2_to_v4.0.csv`](https://github.com/dr5hn/countries-states-cities-database/releases/download/v4.0/removed_ids_v3.2_to_v4.0.csv) 页:1 [上游 v 4.0 释放](https://github.com/dr5hn/countries-states-cities-database/releases/tag/v4.0)它确定了合并的身份证及其幸存者、迁移到新身份证的县以及退休的州及其继任者。 符合 `record`, (中文(简体) ), `outcome`,以及 `new_table` 使用前的列 `new_id`;一个县ID不是城市ID. 根据这个快照刷新存储的州协会 .

城市 `type` 使用标准术语(`municipality`, (中文(简体) ), `city`, (中文(简体) ), `town`, (中文(简体) ), `village`, (中文(简体) ), `locality`, (中文(简体) ), `section`对于移徙国家;其他国家可以保留较早的用语,例如: `adm1`编号 :`adm2`。本套件有意对上游领域进行子集项目: `type_local`, (中文(简体) ), `county_id`, (中文(简体) ), `level`,以及 `parent_id` 在城市/州记录中省略,不运出县数据集。 城市翻译为空对象;包含国家翻译. 当您需要正式的本地术语、 县级链接或分级时, 使用上游出口 .

## \* 特性

-   🌍 **完整数据**:250+国家,5 000+州,15万+城市
-   🌐 **浏览器- Native**: 通过获取和jsDelivr CDN在任何浏览器中直接运行
-   🚀 **最小套装**: < 10KB 初始负载, 懒散地装入其他所有负载
-   🔄 **懒惰装入**: 点取——只装入所需
-   🌐 **翻译**: 支持18+语言
-   ⏰ **时区数据**: 每个地点的全时区信息
-   📝 **类型脚本**: 包括完整类型定义
-   🔧 **可配置**: 可选的 CDN 覆盖和缓存调试

## \* 安装

```bash
npm install @countrystatecity/countries-browser
# or
yarn add @countrystatecity/countries-browser
# or
pnpm add @countrystatecity/countries-browser
```

## QQ 快速启动

```typescript
import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries-browser';

// Load all countries (~30KB gzipped)
const countries = await getCountries();
console.log(countries[0]);
// { id: 1, name: "United States", iso2: "US", emoji: "🇺🇸", ... }

// Load states for a country (on-demand)
const states = await getStatesOfCountry('US');
console.log(states[0]);
// { id: 1, name: "California", iso2: "CA", ... }

// Load cities for a state (on-demand)
const cities = await getCitiesOfState('US', 'CA');
console.log(cities[0]);
// { id: 1, name: "Los Angeles", latitude: "34.05", ... }
```

## 本地包还是活的API?

这个软件包免费地传送了CDN托管的数据快照——当应用程序必须首先下线工作时,这仍然是正确的选择,一个周期快照就足够了,或者你只需要简单的看/倒.

这个 [国家 API](https://countrystatecity.in/) 当您需要时, 值得同时加入:

-   **新鲜度** ——不发布新包版本而更新的数据.
-   **搜索** 模糊、耐打字、服务器侧搜索(`csc.search.fuzzy(...)`),而不只是精确匹配的本地外观.
-   **缩放支持( S)** ——可配置的速率限制和超过捆绑快照的支持.

**每月有3 000个请求免费开始.** [比较计划](https://countrystatecity.in/pricing?source=npm&campaign=sdk_api_migration&package=countries-browser) 或者说 [获取 API 密钥](https://app.countrystatecity.in/?source=npm&campaign=sdk_api_migration&package=countries-browser)。 。 。 .

```bash
npm install @countrystatecity/sdk
```

```typescript
// Before
import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries-browser';

const countries = await getCountries();
const states = await getStatesOfCountry('US');
const cities = await getCitiesOfState('US', 'CA');
```

```typescript
// After
import { createCSCClient } from '@countrystatecity/sdk';

const csc = createCSCClient({ apiKey: process.env.CSC_API_KEY! });

const { data: countries } = await csc.countries.list();
const { data: states } = await csc.states.list({ country: 'US' });
const { data: cities } = await csc.cities.list({ country: 'US', state: 'CA' });
```

见 [完整移徙指南](https://github.com/dr5hn/countrystatecity-npm/blob/main/packages/sdk/MIGRATION.md) 用于错误处理、重试等等.

## API 参考

### 核心职能

#### `getCountries()`

获得所有国家的轻量级列表(仅基本信息).

-   **回返情况:** `Promise<ICountry[]>`

#### `getCountryByCode(code: string)`

获得完整的国家元数据,包括时区和翻译.

-   **参数:** `code` - ISO2代码(例如“美国”)
-   **回返情况:** `Promise<ICountryMeta | null>`

#### `getStatesOfCountry(countryCode: string)`

为一国取出一切州/道.

-   **参数:** `countryCode` - ISO2 代码
-   **回返情况:** `Promise<IState[]>`

#### `getStateByCode(countryCode: string, stateCode: string)`

获取具体状态细节.

-   **参数:** `countryCode`, (中文(简体) ), `stateCode`
-   **回返情况:** `Promise<IState | null>`

#### `getCitiesOfState(countryCode: string, stateCode: string)`

将所有城市都控制在特定状态.

-   **参数:** `countryCode`, (中文(简体) ), `stateCode`
-   **回返情况:** `Promise<ICity[]>`

#### `getCityById(countryCode: string, stateCode: string, cityId: number)`

以数字标识获取特定城市.

-   **参数:** `countryCode`, (中文(简体) ), `stateCode`, (中文(简体) ), `cityId`
-   **回返情况:** `Promise<ICity | null>`

#### `getAllCitiesOfCountry(countryCode: string)`

把全国的城市都找来.

-   **警告:** 较大数据大小, 少用
-   **回返情况:** `Promise<ICity[]>`

#### `getAllCitiesInWorld()`

遍及全球.

-   **警告:** MASSIVE数据(8MB+),极少需要
-   **回返情况:** `Promise<ICity[]>`

#### `getRegions()`

获取所有地区(大陆)列表.

-   **回返情况:** `Promise<IRegion[]>`

#### `getSubregions()`

获取所有分区列表 .

-   **回返情况:** `Promise<ISubregion[]>`

### 工具函数

#### `isValidCountryCode(code: string)`

检查国家代码是否存在 .

-   **回返情况:** `Promise<boolean>`

#### `isValidStateCode(countryCode: string, stateCode: string)`

检查一个国家是否存在国家代码 .

-   **回返情况:** `Promise<boolean>`

#### `searchCitiesByName(countryCode: string, stateCode: string, term: string)`

以部分名称匹配搜索城市.

-   **回返情况:** `Promise<ICity[]>`

#### `getCountryNameByCode(code: string)`

从代码中获取国名.

-   **回返情况:** `Promise<string | null>`

#### `getStateNameByCode(countryCode: string, stateCode: string)`

从代码中获取州名.

-   **回返情况:** `Promise<string | null>`

#### `getTimezoneForCity(countryCode: string, stateCode: string, cityName: string)`

获取特定城市的时区.

-   **回返情况:** `Promise<string | null>`

#### `getCountryTimezones(countryCode: string)`

得到所有的时间区 一个国家.

-   **回返情况:** `Promise<string[]>`

#### `getSubregionsOfRegion(regionId: number)`

把属于某个区域的所有次区域都弄来.

-   **回返情况:** `Promise<ISubregion[]>`

#### `getCountriesByRegion(region: string | number)`

将区域内的所有国家按名称排列(如对案件不敏感). `'Europe'`)或区域身份证.

-   **回返情况:** `Promise<ICountry[]>`

#### `getCountriesBySubregion(subregion: string | number)`

将分区域的所有国家按名称排列(对案件不敏感,例如:. `'South America'`或次区域身份证.

-   **回返情况:** `Promise<ICountry[]>`

### 配置

```typescript
import { configure, resetConfiguration, clearCache } from '@countrystatecity/countries-browser';

// Self-host data instead of jsDelivr
configure({
  baseURL: 'https://my-cdn.com/data',
  timeout: 10000,
  cacheSize: 100,
});

// Reset to defaults
resetConfiguration();

// Clear in-memory cache
clearCache();
```

### 反应示例

```tsx
import { useState, useEffect } from 'react';
import { getCountries, getStatesOfCountry, getCitiesOfState } from '@countrystatecity/countries-browser';
import type { ICountry, IState, ICity } from '@countrystatecity/countries-browser';

export function LocationSelector() {
  const [countries, setCountries] = useState<ICountry[]>([]);
  const [states, setStates] = useState<IState[]>([]);
  const [cities, setCities] = useState<ICity[]>([]);
  const [selectedCountry, setSelectedCountry] = useState('');
  const [selectedState, setSelectedState] = useState('');

  useEffect(() => {
    getCountries().then(setCountries);
  }, []);

  useEffect(() => {
    if (!selectedCountry) { setStates([]); return; }
    getStatesOfCountry(selectedCountry).then(setStates);
  }, [selectedCountry]);

  useEffect(() => {
    if (!selectedCountry || !selectedState) { setCities([]); return; }
    getCitiesOfState(selectedCountry, selectedState).then(setCities);
  }, [selectedCountry, selectedState]);

  return (
    <div>
      <select value={selectedCountry} onChange={(e) => { setSelectedCountry(e.target.value); setSelectedState(''); }}>
        <option value="">Select Country</option>
        {countries.map(c => <option key={c.iso2} value={c.iso2}>{c.name}</option>)}
      </select>
      <select value={selectedState} onChange={(e) => setSelectedState(e.target.value)} disabled={!selectedCountry}>
        <option value="">Select State</option>
        {states.map(s => <option key={s.iso2} value={s.iso2}>{s.name}</option>)}
      </select>
      <select disabled={!selectedState}>
        <option value="">Select City</option>
        {cities.map(c => <option key={c.id} value={c.id}>{c.name}</option>)}
      </select>
    </div>
  );
}
```

### 处理错误

```typescript
import { getCountries, NetworkError } from '@countrystatecity/countries-browser';

try {
  const countries = await getCountries();
} catch (error) {
  if (error instanceof NetworkError) {
    console.error(`CDN request failed: ${error.statusCode} at ${error.url}`);
  }
}
```

无效的代码返回 `null` 或者说 `[]` 优雅地——无一例外.

## QQ 类型脚本

```typescript
import type { ICountry, ICountryMeta, IState, ICity, IRegion, ISubregion, ITimezone } from '@countrystatecity/countries-browser';
```

## QQ 套装大小

| 行动 | 套装大小 |
| --- | --- |
| 安装导入( I) | ~ 5KB 键 |
| 装入国 | ~30KB 击出 |
| 装入美国状态 | ~30千贝 |
| 装入 CA 城市 | ~ 15KB 键 |
| **典型用途** | **~50KB 坐标** |

### 服务器与浏览器比较

|  | `@countrystatecity/countries` (服务器) | `@countrystatecity/countries-browser` |
| --- | --- | --- |
| 环境 | 只有节点.js | 浏览器+节点.js |
| 数据加载 | `fs.readFileSync` | `fetch()` 从CDN |
| 初始捆绑 | ~ 5KB 键 | ~ 5KB 键 |
| 配置 | 无需 | 可选 CDN 覆盖 |
| 懒惰装入 | 对 | 对 |

## 测试

```bash
# Run all tests
npm test

# Watch mode
npm run test:watch
```

所有软件包包括全面测试:

-   单位测试
-   综合测试
-   iOS/Safari兼容性测试

## ++CI/CD和自动化

### 持续整合

每一次推和公关自动:

-   QQ 运行类型检查
-   \* 执行全面测试
-   QQ 构建软件包
-   校验捆绑大小
-   iOS/Safari 兼容性测试

### 自动出版

自动向国家预防机制发布版本变化:

-   QQ 检测软件包中的版本出错. json
-   发布前的构建和测试
-   国家防范机制登记册出版物
-   QQ 创建带有更改日志的 GitHub 发布

## 许可证

[ODbL-1.0. 导弹](https://npmcn.com/package/%40countrystatecity/countries-browser/LICENSE) © [驱动器5hn](https://github.com/dr5hn)

此软件包及其数据由开放数据库许可证(ODbL)v1.0许可. 数据来源于 [国家城市数据库](https://github.com/dr5hn/countries-states-cities-database) 也根据ODbL-1.0获得许可证.

您可以自由分享,创建,并修改这个数据库,只要您将原始源属性化,在同一许可证下发布修改,并且不要使用技术限制来锁定数据.

## 捐款

欢迎捐款! 请打开一个问题或公关.

**数据相关问题** (不正确的国名、缺失的城市、错误的坐标等) [国家城市数据库](https://github.com/dr5hn/countries-states-cities-database/issues) 寄存器,是此软件包的数据源.

## 成套生态系统

此软件包是 [@ 国家状态包生态系统](https://github.com/dr5hn/countrystatecity-npm)数字 :

-   **[@ 国家/ 国家](https://www.npmjs.com/package/@countrystatecity/countries)** ——服务器侧国家,州和城市数据库. 环境:Node.js, Next.js API路线,快通. Bundle: <10KB初始负载.
    
-   **[@ 国家状态/ 国家浏览器](https://www.npmjs.com/package/@countrystatecity/countries-browser)** (本套件)-浏览器-内置版本有jsDelivr CDN并懒惰地加载. 环境:React,Vue,Svelte,Vite,任意浏览器. 与服务器包相同的API——零配置,只是导入和使用.
    
-   **[@ 国家状态/ 时区](https://www.npmjs.com/package/@countrystatecity/timezones)** - 具有转换功能的综合时区数据。 环境:只有服务器侧. Bundle: <20KB初始负载.
    

## 链接

-   [GitHub 仓库](https://github.com/dr5hn/countrystatecity-npm/tree/main/packages/countries-browser)
-   [问题](https://github.com/dr5hn/countrystatecity-npm/issues)
-   [国家防范机制一揽子计划](https://www.npmjs.com/package/@countrystatecity/countries-browser)
-   [国家预防机制组织](https://www.npmjs.com/org/countrystatecity)

## 常见问题

### @countrystatecity/countries-browser 是什么？

有 jsDelivr CDN 和懒惰加载的浏览器本土国家、州和城市数据

### 如何安装 @countrystatecity/countries-browser？

在项目目录运行 npm install @countrystatecity/countries-browser，或使用 pnpm add / yarn add / bun add。

### @countrystatecity/countries-browser 支持 TypeScript 吗？

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

### @countrystatecity/countries-browser 支持 ESM 还是 CommonJS？

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

### @countrystatecity/countries-browser 可以商用吗？

@countrystatecity/countries-browser 使用 ODbL-1\.0 许可。声明的许可为 ODbL-1\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @countrystatecity/countries-browser 的下载量有多少？

根据 npm 官方下载统计，@countrystatecity/countries-browser 在 2026/10/11 – 2026/11/09 这 30 天内被下载 42,825 次，日均约 1,428 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @countrystatecity/countries-browser 还在维护吗？

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