简介全国省市区县数据2024年最新版以JSON格式提供覆盖全国省市县细致到区县包含3465个行政区域节点并附带行政区域代码。适合前端开发、数据可视化、地图服务、电商物流等需要标准行政区划数据的场景可直接用于地址选择器、区域统计分析、配送范围设置等功能开发。资源打包为1个zip压缩包内含1个JSON数据文件整体仅32KB文件结构清晰内容约14797行便于程序化读取与解析。数据更新至2024年7月24日特别完善了香港、澳门地区的行政区划代码同时补充了东莞市、中山市的镇街信息并覆盖台湾省各市县及港澳分区解决了常见数据缺失或代码不准确的问题。目前已有2015人学习下载适合需要最新、完整且带行政区域代码的省市县数据的开发者和数据分析师使用。 做前端开发这些年我最大的体会之一就是全国省市县三级联动数据是每个业务系统几乎都绕不开的“基础配置”。不管是做后台管理系统里的收货地址、电商的配送区域还是企业内部的组织架构映射都需要一份准确、更新及时的省市区县JSON数据。最近我重新整理并发布了2024年最新版的全国省市区县数据一共3465个JSON文件覆盖省、市、区县三个层级。如果你也在为手头那份“数据已经过时”或“结构乱七八糟”的地址库发愁这篇内容我建议你花几分钟看完我把数据组织逻辑、字段结构、更新校验流程以及实际接入业务时的踩坑经验都放在里面。数据这东西看着简单真正用起来才知道坑有多深。尤其是行政区划数据每年都有调整撤县设区、新设街道、名称变更稍不留神线上就出bug。我这套数据不是简单地从某个数据库导出就完事而是经过了清洗、去重、编码校验和目录拆分后端同学可以直接落地成接口前端同学拿去做级联选择器也几乎不用改代码。1. 项目背景为什么我需要一份“干净”的省市县JSON数据1.1 开发者最容易踩的“数据坑”我先说一个真实经历。早年间做电商后台运营反馈说某个城市下单时总是定位不到区县。查了半天发现我们用的还是好几年前的行政区划数据里面连“新设的市辖区”都没有收录。后来更头疼的问题是不同系统之间数据格式还不一样有的用name有的用fullName有的areaCode还是字符串有的却是整数。数据一旦跟业务代码耦合后期想替换成本极高。所以当我自己再做类似项目时就下定决心要整理一份标准化的JSON数据。2024年最新版的整理思路很简单一份数据多端复用。后端拿去做省市县下拉接口前端拿来做级联选择器数据分析组拿去做地图可视化全都能用这才是这份数据存在的核心价值。1.2 3465个文件是怎么拆分出来的你可能好奇3465这个数字是怎么来的。简单解释一下我按照最新的行政区划代码把全国数据拆成了三层粒度每一层都有独立文件。省级文件34个包含省份、直辖市、自治区、特别行政区地市级文件330余个包含地级市、自治州、地区、盟区县级数据3100余个包含市辖区、县级市、县、自治县、旗等这样拆分的好处是前端在做“按省加载城市”“按市加载区县”的异步请求时天然就能对齐接口粒度不需要把一份巨大的JSON全部塞进内存。实测下来首次渲染性能和后续按需请求的体验都会好很多。2. 数据结构设计与文件组织方案2.1 单文件JSON字段是怎么设计的字段设计是整个数据好不好用的关键。我见过很多版本的数据有的字段叫id有的叫code有的叫value拿过来还得自己再包一层适配。这份2024年数据的单文件结构尽量保持“一眼能看懂”核心字段如下字段名类型说明示例codestring行政区划代码统一用6位字符串110000namestring行政区划名称北京市levelnumber层级1省级/2地级/3区县1parentCodestring父级区划代码省级为00shortNamestring简称北京pinyinstring全拼beijingcityCodestring区号部分区县为空010关于code字段我特别提醒一句事业单位和互联网公司对接时经常遇到编码格式不统一的问题。有的系统把“110000”读成数字110000前导零就丢了。所以这份数据里我强制把code、parentCode全部定义为字符串并且在文档里标注了“禁止直接转Number”这样能避免绝大部分低级bug。2.2 文件目录的组织模式3465个文件不可能全扔同一个目录否则查找和管理都是灾难。我采用的是“data/省级代码/市级代码/区县代码.json”这样的三级目录结构每个JSON文件名直接以区划代码命名。data/ ├── 110000.json ├── 110100.json ├── 110102.json ├── 110103.json ├── 410000.json ├── 410100.json ├── 410102.json └── ...我最开始试图用“省市县三级各一个总文件”的最小化方案后来发现实际使用并不方便。电商后台的收货地址往往需要“省-市-区”三个独立接口移动端还要做联动按区划代码拆文件反而更契合这些场景。你要是存数据库也可以直接把文件名当主键索引查询走覆盖索引性能很稳。3. 数据来源、清洗与2024年更新校验流程3.1 数据源怎么选官方代码为主地图API为辅这里我得说清楚行政区划数据的权威源头是国家统计部门公布的全国统计用区划代码和城乡划分代码。这套代码的维护节奏基本是每年更新一次大概在下半年发布。我的整理流程是先抓取官方最新公布的标准代码解析出省、市、县三级再跟主流地图服务平台的行政区域接口交叉比对标记出“名称不一致”“编码不存在”的条目人工核对差异项确认之后才合入最终数据为什么要跟地图API交叉验证因为官方代码偏统计口径但很多业务系统对接的是地图服务的行政区域体系两边偶尔会在“飞地”“经济功能区”这种特殊区域上存在描述差异。提前比对能减少线上问题但也别完全依赖某一个API不同服务商之间本身也会有出入。3.2 编码规则与去重逻辑区划代码看着是一串数字实际有规律可循。6位编码中前两位是省级代码中间两位是地级代码后两位是区县级代码。我写了一个校验脚本用正则和分段逻辑检查每一个文件省级文件后四位必须是“00”市级文件中间两位不能为空后两位为“00”区县级文件六位必须全量填满这套校验能拦住绝大多数“手误”。同时我还做了名称去重比如有些市辖区在官方表里会出现同名情况但在不同地级市下其实是合法的所以去重逻辑必须带上parentCode一起判断不能只按name去重。3.3 2024年更新了哪些东西2024年这版相较2023年主要变化集中在部分撤县设区、县级市升格和新区成立。比如有些原县级区域调整为市辖区名称从“县”变成“区”对应的code和level都会变。我对比了前后两版差异项全部用diff脚本标记过在发布包里的CHANGELOG.md中做了记录。我的建议是如果你正在维护的线上系统还在用老数据务必关注上一版变更了哪些区划因为老的县级code很可能已经废弃再拿旧code去下单很可能会被驳回。4. 实际业务场景接入实践4.1 省市联动选择器前端接入先给前端同学一个可直接参考的案例。现在大部分项目都在用Vue或者React联动选择器一般有两种做法一次性加载全部数据或者按级联异步加载。如果你用这份3465个JSON文件我推荐后者比如在用户选择省份之后再加载对应城市列表// 以 Vue3 Element Plus 为例 const provinceList ref([]) const cityList ref([]) const districtList ref([]) const loadProvince async () { const res await fetch(/api/region/provinces) provinceList.value res.data } const onProvinceChange async (provinceCode) { // 加载该省下所有地级市 const res await fetch(/api/region/cities?parentCode${provinceCode}) cityList.value res.data districtList.value [] }后端的接口逻辑也很简单直接读对应层级的JSON文件返回即可。为了防止文件读取IO太频繁我建议在服务启动时把全部数据load到内存用Map建立code - data的索引查询就是一次内存取值。4.2 地图可视化场景下的JSON处理另一个高频场景是地图可视化最常见的是用ECharts画省份分布图。这种场景需要把“区划名称”和业务数据进行映射但地图组件和业务数据的名称不一定完全一致比如地图里叫“广西”业务库里存的是“广西壮族自治区”。这时候就体现出shortName字段的价值了// 用 shortName 做匹配能兼容大多数地图组件 const mapName row.shortName || row.name seriesData.push({ name: mapName, value: row.value })这里有个小技巧很多地图GeoJSON文件里的省份名称其实并不统一有的带“省”“市”后缀有的不带。你可以先用这份JSON数据生成一份“全名-简称”的映射表再跑一次循环把所有名称归一化之后的数据合并就清爽多了。4.3 后端接口设计中的性能与缓存策略后端接入时我倾向于把这套JSON作为“静态资源”处理而不是频繁查库。具体做法是项目启动时一次性加载到Redis或者本地内存缓存缓存key可以设计成region:province、region:city:{code}、region:district:{code}。因为行政区划数据属于“读多写少”的典型数据缓存过期时间直接设置成24小时起步完全没问题。如果团队有动态更新需求也可以额外开发一个管理后台让运营手动选择“启用新版本数据”更新时重新生成缓存即可。实际操作中我发现很多系统出问题不是因为数据不更新而是更新之后缓存没清干净用户看到的还是旧地址。缓存key里带一个版本号每次发布新数据版本时整体后缀变更是最稳妥的做法。5. 常见问题与排查技巧实录5.1 JSON文件加载失败或编码异常我遇到最多的反馈是明明文件路径没问题但解析JSON时报错或者是打开文件后中文变成乱码。排查思路主要有三条确认文件编码是UTF-8不要用GBK编码保存确认项目构建工具没有对.json文件做额外转义如果通过nginx托管静态文件确认响应头里的Content-Type是application/json; charsetutf-8而不是默认的application/octet-stream还有一个比较隐蔽的坑某些Windows服务器环境默认编码不是UTF-8fs.readFile读JSON时没指定encoding导致中文乱码。正确写法是const data JSON.parse(fs.readFileSync(/path/to/110000.json, utf-8))5.2 3465个文件在低端设备上的性能问题有开发者反馈在低配手机或老版本浏览器上如果一次性把所有JSON都加载到前端页面会卡顿。这其实不是数据文件的问题而是使用方式的问题。解决办法就是前面说的按需加载、懒加载。城市列表和区县列表只在用户选中上级后才请求效果立竿见影。如果项目是纯静态页面没有后端接口也可以考虑提供一个“合并后的总量文件”但我建议合并文件不要超过3MB超过3MB后移动端弱网环境体验会明显下降。我最终保留了两种发布物按层级拆分的3465个文件以及一个total.json汇总文件方便有不同需求的人选择。5.3 版本更新后旧编码失效怎么办行政区划代码具有连续性但每年都会有一些废弃不用的旧代码比如某个县改成区后原县代码就停用了。如果你的系统里有历史订单存储了旧code又需要用新数据展示最简单的方案是在后端维护一张“旧code-新code映射表”。之前有个订单系统用户查看历史订单地址时传入的code已经失效导致页面无法显示省市县名称。我当时的处理方式是在读取区划数据时先查一次映射表如果旧code存在就直接翻译成新code再查名称。这样既保证了历史数据可显示又不需要回刷大量历史订单。5.4 浏览器打开JSON不格式化的处理很多人问“为什么我把JSON文件拖到Chrome里显示的还是纯文本一点都不好看”。这是因为默认情况下JSON文件在浏览器里会被当成纯文本渲染浏览器自己没有JSON美化功能。解决办法很轻量安装JSON Formatter这类扩展或者本地用VS Code、Notepad打开它们都有内置的格式化功能。但如果你做的是数据对接我更推荐直接用命令行工具做格式化验证比如python3 -m json.tool 110102.json如果执行后能正常输出带缩进的JSON说明文件本身没问题之后再排查业务代码。6. 这套数据后续还能怎么扩展整理完这套2024年版本的省市县数据之后我还做一些额外加工比如补充了部分四线城市及以上城市的中心点经纬度坐标因为做地图撒点场景时经纬度是刚需。后续我还计划把乡镇街道一级的数据也汇总整理成类似格式如果你有相关的业务需求可以重点关注。另外在做这套数据的过程中我也养成了一个习惯每年年初固定检查一次上一年的区划代码变更公告把差异记录下来而不是等到线上出问题再去补数据。这个习惯看起来简单但真的能帮你省下大量无意义的加班时间。如果你也维护过类似的基础数据应该懂我说的这种感觉。本文还有配套的精品资源点击获取