# @countrystatecity/countries 中文文档

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

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

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

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

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

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

## 中文简介

有iOS/Safari支持和最小捆绑规模的官方国家、州和城市数据库

## 安装

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

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

## README

# @ 国家/ 国家

[![npm](https://img.shields.io/npm/v/@countrystatecity/countries)](https://www.npmjs.com/package/@countrystatecity/countries) [![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?label=countries)](https://www.npmjs.com/package/@countrystatecity/countries) [![npm downloads](https://img.shields.io/npm/dw/@countrystatecity/countries?label=countries)](https://www.npmjs.com/package/@countrystatecity/countries)

官方国家、州和城市数据库有iOS/Safari支持,最小捆绑大小.

**环境:** 🖥️ **仅服务器侧** (Node.js, Next.js API线路,快递等)

## 升级到 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万+城市
-   📱 **iOS 兼容**: Safari/iOS 浏览器上没有堆栈溢出错误
-   🚀 **最小套装**: < 10KB 初始负载, 懒散地装入其他所有负载
-   🔄 **懒惰装入**: 动态进口,以达到最佳性能
-   🌐 **翻译**: 支持18+语言
-   ⏰ **时区数据**: 每个地点的全时区信息
-   📝 **类型脚本**: 包括完整类型定义
-   🔧 **可树动**: 只捆绑您使用的

### 为什么是这个包裹?

大众 `country-state-city` 软件包(162K每周下载)有关键问题:

-   QQ 8MB 捆绑大小( 包括全部数据)
-   iOS Safari 有堆叠溢出错误的崩溃
-   未保存2年以上
-   静态进口强制整捆

此套件解决了其中每一个问题:

-   最小捆绑( < 10KB 初始)
-   动态导入和懒惰加载
-   iOS/Safari 兼容
-   QQ 总是从权威数据库更新
-   & 代码可分割

## \* 安装

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

> **仅使用服务器**:此软件包需要Node.js文件系统访问,无法在浏览器环境中被使用. 用于前端, 安装 [`@countrystatecity/countries-browser`](https://www.npmjs.com/package/@countrystatecity/countries-browser) 相反——相同的API,在React/Vue/Svelte/Vite中工作.

## QQ 快速启动

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

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

// Get all states in a country (~10-100KB depending on country)
const states = await getStatesOfCountry('US');
console.log(states[0]);
// { id: 1, name: "California", iso2: "CA", ... }

// Get all cities in a state (~5-200KB depending on state)
const cities = await getCitiesOfState('US', 'CA');
console.log(cities[0]);
// { id: 1, name: "Los Angeles", latitude: "34.05", ... }
```

## 本地包还是活的API?

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

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

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

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

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

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

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[]>`
-   **套装影响 :** ~ 5KB 键

#### `getCountryByCode(countryCode: string)`

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

-   **参数:** `countryCode` - ISO2代码(例如“美国”)
-   **回返情况:** `Promise<ICountryMeta | null>`
-   **套装影响 :** 每个国家~5KB

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

为一国取出一切州/道.

-   **参数:** `countryCode` - ISO2 代码
-   **回返情况:** `Promise<IState[]>`
-   **套装影响 :** ~10-100KB,视国家而定

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

获取具体状态细节.

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

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

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

-   **参数:** `countryCode`, (中文(简体) ), `stateCode`
-   **回返情况:** `Promise<ICity[]>`
-   **套装影响 :** ~5-200KB 取决于状态

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

把全国的城市都找来.

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

#### `getAllCitiesInWorld()`

遍及全球.

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

#### `getRegions()`

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

-   **回返情况:** `Promise<IRegion[]>`
-   **套装影响 :** ~ 3KB 键

#### `getSubregions()`

获取所有分区列表 .

-   **回返情况:** `Promise<ISubregion[]>`
-   **套装影响 :** ~13KB (英语)

### 工具函数

#### `isValidCountryCode(countryCode: string)`

检查国家代码是否存在 .

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

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

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

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

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

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

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

#### `getCountryNameByCode(countryCode: 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[]>`

## QQ 类型脚本

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

## QQ 套装大小

| 行动 | @ 国家/ 国家 | 国家-国家-城市 |
| --- | --- | --- |
| 安装导入( I) | 5个KB | 8MB (英语) |
| 装入国 | +2KB 组合键 | \- 说吧 |
| 装入美国状态 | +30KB 键 | \- 说吧 |
| 装入 CA 城市 | +15KB 组合键 | \- 说吧 |
| **典型用途共计** | **~50KB 坐标** | **8MB (英语)** |

**160个小包!**

## 测试

```bash
# Run all tests
npm test

# Run iOS compatibility tests specifically
npm run test:ios

# 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/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初始负载.
    

### 环境指南

**使用此软件包( E)`@countrystatecity/countries`当:**

-   QQ 构建 API 端点或后端
-   使用 Next.js App 路由器服务器组件
-   QQ 在 Node.js 中运行,无服务器功能(Vercel, AWS Lambda)
-   QQ 有文件系统访问
-   建设命令行工具

**浏览器/ 前端使用 :**

使用 [`@countrystatecity/countries-browser`](https://www.npmjs.com/package/@countrystatecity/countries-browser) ——同名API,直接在React,Vue,Svelte,Vite工作:

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

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

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

## 链接

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

## 常见问题

### @countrystatecity/countries 是什么？

有iOS/Safari支持和最小捆绑规模的官方国家、州和城市数据库

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

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

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

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

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

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

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

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

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

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

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

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