Go 是 Google 的 libphonenumber 的移植。具体来说，它跟踪了 Java 实现——该库的参考实现，C++ 和 JavaScript 版本本身就是其移植。该库每天都在生产中使用，用于数字解析和验证，维护良好。

[!重要] 本项目是 libphonenumber 的严格移植。请不要提交 libphonenumber 不存在的功能请求。它也使用 libphonenumber 的元数据，因此如果你遇到意外的解析结果，请先确认问题是否影响 libphonenumber，并报告。你可以使用在线演示快速查看解析结果。

[!提示] 关于从 1.x 升级到 2.x 的详细信息，请参见 UPGRADING.md。

安装

用途

更新中

元数据

buildmetadata 命令是从上游发布中重新生成嵌入的元数据。它 克隆发布并重建嵌入在包（核心）上的 gzip 数据块 地区元数据、简短号码、替代格式、国家代码→地区、运营商， 地理编码和时区），记录它所构建的释放，生成的 metadata/version.go。

☎️ phonenumbers

Go port of Google’s libphonenumber. Specifically it tracks the Java implementation — that library’s reference implementation, of which the C++ and JavaScript versions are themselves ports. This library is used daily in production for parsing and validation of numbers worldwide and is well maintained.

[!IMPORTANT] This project is a strict port of libphonenumber. Please do not submit feature requests for functionality that doesn’t exist there. It also uses the metadata from libphonenumber, so if you encounter unexpected parsing results, please first verify if the problem affects libphonenumber and report there if so. You can use the online demo to quickly check parsing results.

[!TIP] See UPGRADING.md for details on upgrading from 1.x to 2.x.

Installation

% go get github.com/nyaruka/phonenumbers/v2

Usage

import "github.com/nyaruka/phonenumbers/v2"

// parse our phone number
num, err := phonenumbers.Parse("8886418722", "US")

// check if it's a valid number for its region
valid := phonenumbers.IsValidNumber(num)

// format it using national format
formatted := phonenumbers.Format(num, phonenumbers.NATIONAL)

Updating

Metadata

The buildmetadata command regenerates the embedded metadata from an upstream release. It clones the release and rebuilds the gzipped data blobs embedded across the packages (core territory metadata, short numbers, alternate formats, country-code→region, carrier, geocoding, and timezone), recording the release it built from in the generated metadata/version.go.

# resolve and build from the latest upstream release
% go run ./cmd/buildmetadata

# or pin a specific release tag
% go run ./cmd/buildmetadata v9.0.31

This part is mechanical and fully automated.

Code

Regenerating the metadata is only half of a sync — the ported Go code also has to be reconciled against the new release’s Java logic changes, which is judgment work rather than a mechanical rebuild.

If you use Claude Code, the sync-upstream skill (.claude/skills/sync-upstream/SKILL.md) walks through the whole process — metadata regen plus the per-file code reconciliation. Invoke it with /sync-upstream or by asking it to sync with upstream. SYNC.md records the upstream version the port is synced against and the deliberate divergences from upstream.