快速开始 – tzf 项目

快速开始

Project tzf 支持多种语言和服务，可根据经纬度查询时区。

语言或服务	仓库	API 文档
Go	`ringsaturn/tzf`
Rust	`ringsaturn/tzf-rs`
Python	`ringsaturn/tzfpy`	`tzfpy.pyi`
Swift	`ringsaturn/tzf-swift`
Ruby	`HarlemSquirrel/tzf-rb`
JS (浏览器 Wasm)	`ringsaturn/tzf-wasm`
HTTP API	`racemap/rust-tz-service`
在线演示	`ringsaturn/tzf-web`

Go

tzf v2 是新的主版本，因此模块路径带有 /v2 后缀：

go get github.com/ringsaturn/tzf/v2

package main

import (
	"fmt"

	"github.com/ringsaturn/tzf/v2"
)

func main() {
	// 相对于一次查询，构造开销较大，查找器只构建一次。
	finder, err := tzf.NewDefaultFinder()
	if err != nil {
		panic(err)
	}
	// 坐标采用 (经度，纬度) 顺序。
	fmt.Println(finder.GetTimezoneName(116.6386, 40.0786))
}

共有五个构造函数，全部返回 tzf.F 接口：

构造函数	适用场景
`NewDefaultFinder()`	通用场景：lite 内存镜像，~12 MB 堆 + 10 MB 只读数据，查询 298 ns
`NewEmbeddedFinder()`	嵌入式和内存受限目标：合计约 4 MB，预索引未命中时查询约 1.2 µs
`NewFullFinder()`	结果与完整精度数据集一致（~145 MB）
`NewFinderFromTZB(data)`	调用方提供的 `.tzb` 字节，加载时展开
`NewFinderFromTZM(data)`	调用方提供的 `.tzm` 字节，原地引用

以上数据在 Apple M3 Max 上针对 2026c 数据集测得。

如需 100% 准确的结果，请使用 NewFullFinder。该实例初始化开销较大，建议尽可能复用：

package main

import (
	"fmt"

	"github.com/ringsaturn/tzf/v2"
)

func main() {
	finder, err := tzf.NewFullFinder()
	if err != nil {
		panic(err)
	}
	fmt.Println(finder.GetTimezoneName(139.6917, 35.6895))
}

GeoJSON 导出、对自行提供字节的原地查询，以及 v1 到 v2 的迁移对照表，参见 Go 指南。

Rust

cargo add tzf-rs

use std::sync::LazyLock;
use tzf_rs::DefaultFinder;

static FINDER: LazyLock<DefaultFinder> = LazyLock::new(DefaultFinder::new);

fn main() {
    // 坐标采用 (经度，纬度) 顺序。
    print!("{:?}\n", FINDER.get_tz_name(116.3883, 39.9289));
    print!("{:?}\n", FINDER.get_tz_names(116.3883, 39.9289));
}

tzf-rs 2.1 提供两个查找器：DefaultFinder（默认，峰值 RSS 约 47 MiB，随机城市查询 221 ns），以及 EmbeddedFinder，后者原地查询嵌入的文件，占用约 10 MiB，随机城市查询 293 ns，边界城市 666 ns。两者的数据来自 tz-benchmark 的 2026-09-14 快照，在 Apple M3 Max 上针对 2026c 数据集测得 tzf-rs 2.1.1。

完整精度支持

可通过可选 Cargo feature 使用完整精度数据。由于完整数据集约 14 MB，超出 crates.io 的大小限制，需要通过 git 依赖引用，并且它与内置的 lite 数据集互斥：

[dependencies]
tzf-rs = { git = "https://github.com/ringsaturn/tzf-rs", rev = "v{X}.{Y}.{Z}", features = ["full"], default-features = false }

use tzf_rs::DefaultFinder;

fn main() {
    let finder = DefaultFinder::new_full();
    let tz_name = finder.get_tz_name(139.767125, 35.681236);
    println!("tz_name: {}", tz_name);
}

Python

# 只安装 tzfpy
pip install tzfpy

# 安装 pytz 支持
pip install "tzfpy[pytz]"

# 安装 tzdata 支持
pip install "tzfpy[tzdata]"

# 通过 conda 安装
conda install -c conda-forge tzfpy

>>> from tzfpy import get_tz, get_tzs
>>> get_tz(116.3883, 39.9289)   # (经度，纬度) 顺序
'Asia/Shanghai'
>>> get_tzs(87.4160, 44.0400)   # 返回全部匹配时区
['Asia/Shanghai', 'Asia/Urumqi']

tzfpy 2.0 需要 Python 3.10 或更高版本，绑定 tzf-rs 2.0。它还提供 timezonenames()、data_version()、get_tz_polygon_geojson(name) 和 get_tz_index_geojson(name)。完整精度模式以实验性的 +full 预发布 wheel 形式在 tzfpy 自有索引上提供，不发布到 PyPI；参见 Python 指南。

Swift

tzf-swift 2.0 不再依赖 protobuf：它内置 tzf-dist 的 lite.tzb，并提供两个查找器。DefaultFinder 在加载时展开多边形（约 16 ms、约 48 MB），EmbeddedFinder 原地查询 .tzb 字节（约 2 ms、约 10 MB），单次查询延迟更高。两者都可以通过 init(tzb:) 接收调用方提供的字节，因此 tzf-dist 的完整精度 full.tzb 也能以同样方式加载。

将包添加到你的 Package.swift：

dependencies: [
    .package(url: "https://github.com/ringsaturn/tzf-swift.git", from: "2.0.0")
]

import Foundation
import tzf

do {
    let finder = try DefaultFinder()

    let timezone = try finder.getTimezone(lng: 116.3833, lat: 39.9167)
    print("北京时区：", timezone)

    let timezones = try finder.getTimezones(lng: 87.5703, lat: 43.8146)
    print("可能存在的多个时区：", timezones)

    print("数据版本：", finder.dataVersion())

    // 低内存替代方案：原地查询 .tzb 字节。
    let embedded = try EmbeddedFinder()
    print("Embedded finder：", try embedded.getTimezone(lng: 139.6917, lat: 35.6895))
} catch {
    print("错误：", error)
}

从 v1 迁移：Finder() 改为 DefaultFinder()；PreindexFinder 已移除（预索引成为每个查找器内部的快速路径）；FinderError.noTimezoneFound 改为 TZFError.noTimezoneFound；getTimezones 的结果现在按字典序排序。

Ruby

Ruby 版本由 HarlemSquirrel 创建并维护，截至 2026-09-12 基于 v1 系列构建。详细用法请参见 tzf-rb。

bundle add tzf
# 或
gem install tzf

require 'tzf'

TZF.tz_name(40.74771675713742, -73.99350390136448)
# => "America/New_York"

TZF.tz_names(40.74771675713742, -73.99350390136448)
# => ["America/New_York"]

WebAssembly

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>tzf-wasm 示例</title>
    <script type="module">
      import init, { WasmFinder } from "https://www.unpkg.com/tzf-wasm@2.0.0/tzf_wasm.js";

      async function loadWasm() {
        await init();
        const finder = new WasmFinder();
        const timezone = finder.get_tz_name(-74.006, 40.7128);
        console.log("纽约时区：", timezone);
      }

      loadWasm();
    </script>
  </head>
  <body></body>
</html>

在线预览：http://ringsaturn.github.io/tzf-web/

CLI

Go 和 Rust 实现均提供命令行工具。

Go CLI

go install github.com/ringsaturn/tzf/cmd/tzf@latest

tzf -lng 116.3883 -lat 39.9289

# 通过 stdin 批量处理
echo -e "116.3883 39.9289\n116.3883, 39.9289" | tzf -stdin-order lng-lat

Rust CLI

cargo install tzf-rs

tzf --lng 116.3883 --lat 39.9289

# 通过 stdin 批量处理
echo -e "116.3883 39.9289\n116.3883, 39.9289" | tzf --stdin-order lng-lat

NixOS 用户可以通过 Nix 安装 tzf-rs。详见 NixOS packages。

最后更新于 September 14, 2026