GeoPandas to_file 怎么写出文件并指定驱动
GeoPandas 写出矢量文件用 GeoDataFrame.to_file()，通过 driver 参数指定 OGR 驱动；不写 driver 时按扩展名推断，没有扩展名则默认写成 ESRI Shapefile。常见写法是 gdf.to_file(‘out.shp’)、gdf.to_file(‘out.gpkg’, driver=’GPKG’, layer=’图层名’)，或 gdf.to_file(‘out.geojson’, driver=’GeoJSON’)。截至 2026 年 11 月，稳定版 1.2.0 默认引擎为 pyogrio（安装后优先），写入通常比旧版 Fiona 更快，也可用 engine 显式切换。
基本写出步骤怎么做
要解决的问题很直接：把内存里的 GeoDataFrame 落成磁盘文件，并指定目标格式，方便给 QGIS、其他脚本或同事使用。按下面步骤做，并做读回验收。
- 准备环境：确认已安装 GeoPandas（推荐 conda-forge 通道）。1.2.0 要求 Python ≥3.11、pandas ≥2.2、shapely ≥2.1、pyogrio ≥0.8、pyproj ≥3.7。不确定依赖时以本机 pip show geopandas 或 conda 列表为准。
- 得到要写出的 gdf：自己构造，或从已有文件读入。读入 Shapefile 时若遇编码或驱动问题，可先参考本站 GeoPandas 读取 Shapefile 报错与失败处理 排查。
- 调用 to_file 并指定驱动。例如写出 GeoPackage：gdf.to_file(‘result.gpkg’, driver=’GPKG’, layer=’roads’)；写出 GeoJSON：gdf.to_file(‘result.geojson’, driver=’GeoJSON’)；默认 Shapefile：gdf.to_file(‘result.shp’)。
- 中文属性或需固定编码时加上 encoding=’utf-8’（Shapefile 会生成 .cpg）。追加已有文件（部分驱动支持）用 mode=’a’，pyogrio 也可用 append=True。
- 验收：检查目标路径是否生成文件；用 geopandas.read_file 读回，对比行数、几何类型、CRS 与关键属性字段。地图预览可结合本站 GeoPandas 读取 Shapefile 与 GIS 地图可视化 里的画图方法快速核对。
路径支持 GDAL VSI 方案。多几何列时多数格式只认活动几何列，其余需先转成 WKT 或 WKB 再写。
常用驱动怎么选
驱动名必须是 OGR 格式名（如 GPKG），不是随便写的路径。未指定时由扩展名推断。可用 import pyogrio; pyogrio.list_drivers() 查看当前环境读写支持情况。Fiona 引擎下驱动列表见 fiona.supported_drivers，部分格式需手动启用。
| 驱动名 | 常见扩展名 | 适用场景 | 注意点 |
|---|---|---|---|
| ESRI Shapefile | .shp（实际多文件） | 兼容老软件、教学交换 | 字段名最长约 10 字符，易截断；需配套 .shx、.dbf、.prj 等 |
| GPKG | .gpkg | 日常推荐、单文件多图层 | 务必用 layer 指定图层名；支持 metadata（字符串字典） |
| GeoJSON | .geojson / .json | Web、轻量交换、文本可读 | 大文件体积大、读写相对慢 |
不确定选哪个时，优先 GPKG：单文件、少踩坑，适合后续继续用 GeoPandas 或 PostGIS 流转。需要入库而不是落盘文件时，可直接看本站 GeoPandas 写入 PostGIS（to_postgis / read_postgis）。
to_file 关键参数要注意什么
方法签名大致为 to_file(filename, driver=None, schema=None, index=None, **kwargs)。下面按实际使用频率说明。
- driver：字符串，OGR 驱动名。为 None 时从扩展名推断，无扩展名则写成 Shapefile。
- engine：pyogrio（默认，装了就优先）或 fiona。也可全局设置 geopandas.options.io_engine = ‘fiona’。pyogrio 更快，但不支持 schema；需要精细控制字段类型时切 Fiona。
- mode：默认 w 表示覆盖；a 表示追加（并非所有驱动支持）。
- layer：GPKG 等多图层格式必填或强烈建议填写。
- encoding：属性表编码，中文场景常用 utf-8。
- index：是否把索引写成一列（命名索引、MultiIndex 或非整数索引默认会写；0.7 及以后行为）。
- schema：传给 Fiona 控制写入字段；基于 dtype 可自动推断。pyogrio 不支持，需要时必须 engine=’fiona’。
- crs：覆盖写出 CRS（pyogrio 不支持该关键字，以 gdf.crs 为准）。
- metadata：仅 GPKG 支持的字符串字典。
- 其他关键字参数：透传给引擎，例如 use_arrow=True（需 pyarrow，可明显加速）、spatialite=True 等。
字段类型必须被目标驱动支持，否则会抛出 ValueError。几何类型也要匹配（例如某些驱动不接受 LinearRing，需先转成 LineString 或 Polygon）。版本与依赖可在 GeoPandas GitHub 版本标签 与 pyproject.toml 依赖声明 核对；最终以你本机安装版本为准。
写出后验收标准与出错怎么办
验收建议固定三条：文件（及 Shapefile 配套文件）存在且大小合理；read_file 能完整读回，几何与属性行数一致；CRS、字段名与关键属性值与写出前一致（尤其是中文）。不满足就按报错信息对号入座。
- 列名被截断或重名警告：Shapefile 限制，缩短列名或改用 GPKG、GeoJSON。
- 中文乱码或编码失败：加 encoding=’utf-8’；确认读端也用相同编码。
- schema 相关错误：当前默认 pyogrio 不支持，改 engine=’fiona’。
- unsupported driver，或 Geometry type not supported：查 pyogrio.list_drivers()；转换几何类型或换驱动；Fiona 下部分驱动需手动设为可读写。
- 多几何列或复杂 Python 对象（元组、列表）：先简化列，或在业务允许时改用更适合表格加几何的格式。
性能上，大数据量可试 use_arrow=True（需安装 pyarrow）。引擎从 Fiona 迁到 pyogrio 后，EMPTY 几何等行为略有差异，写出前后用同一引擎读回对比更稳妥。
常见问题
不写 driver 会写成什么格式？
有扩展名就按扩展名推断（如 .gpkg 对应 GPKG）；没有扩展名则写成 ESRI Shapefile 文件夹结构。想明确控制时请始终传入 driver。
为什么 schema 参数无效或报错？
默认引擎 pyogrio 不支持 schema。需要自定义字段类型时设置 engine=’fiona’，或全局把 io_engine 改成 fiona。
写出 Shapefile 后字段名变短了怎么办？
这是格式限制（通常最长约 10 字符），GeoPandas 会截断并可能警告。业务字段多时改用 GPKG，并在 layer 参数里起好图层名。
追加写入 mode=’a’ 失败是什么原因？
不是所有驱动都支持追加。先确认当前引擎与驱动是否支持；GPKG 等可优先试 pyogrio 的 append 相关参数，仍失败就改为读出合并后再覆盖写。
总结：用 geopandas to_file 时先定格式再定 driver，日常优先 GPKG 并指定 layer，中文加 encoding=’utf-8’，写出后立刻 read_file 验收。需要精细 schema 时切 Fiona；需要入库而不是文件时直接用 to_postgis。建议把“写出 → 读回对比 CRS、字段、行数”固化成固定检查清单，再按项目选择 Shapefile 兼容方案或 GPKG 现代方案。