Xarray保存NetCDF失败：名称含非法字符排查求助

问题背景 #

我有多个Pandas DataFrame，用df.to_excel('temp/df.xlsx')导出为Excel文件正常，但将这些DataFrame通过xarray拼接为三维数组后，保存为NetCDF文件时触发错误：RuntimeError: NetCDF: Name contains illegal characters，未发现明显非法字符，需要排查解决方法。

代码示例 #

import pandas ad pd  # 存在笔误：ad → as
import xarray as xr

dflist.append(df)
xarray = xr.concat([df.to_xarray() for df in dflist], dim=f'{["stationIDlist"]}')
xarray.to_netcdf('temp/xarray.nc')

错误回溯信息 #

xarray.to_netcdf('temp/xarray.nc', format='NETCDF4')
Traceback (most recent call last):
  File "~/python3.11/site-packages/IPython/core/interactiveshell.py", line 3577, in run_code
    exec(code_obj, self.user_global_ns, self.user_ns)
  File "<ipython-input-19-65321829c66f>", line 1, in <module>
    xarray.to_netcdf('temp/xarray.nc', format='NETCDF4')
  File "~/python3.11/site-packages/xarray/core/dataset.py", line 2327, in to_netcdf
    return to_netcdf(  # type: ignore  # mypy cannot resolve the overloads:(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "~/python3.11/site-packages/xarray/backends/api.py", line 1337, in to_netcdf
    dump_to_store(
  File "~/python3.11/site-packages/xarray/backends/api.py", line 1384, in dump_to_store
    store.store(variables, attrs, check_encoding, writer, unlimited_dims=unlimited_dims)
  File "~/python3.11/site-packages/xarray/backends/common.py", line 366, in store
    self.set_dimensions(variables, unlimited_dims=unlimited_dims)
  File "~/python3.11/site-packages/xarray/backends/common.py", line 443, in set_dimensions
    self.set_dimension(dim, length, is_unlimited)
  File "~/python3.11/site-packages/xarray/backends/netCDF4_.py", line 481, in set_dimension
    self.ds.createDimension(name, size=dim_length)
  File "src/netCDF4/_netCDF4.pyx", line 2710, in netCDF4._netCDF4.Dataset.createDimension
  File "src/netCDF4/_netCDF4.pyx", line 3711, in netCDF4._netCDF4.Dimension.__init__
  File "src/netCDF4/_netCDF4.pyx", line 2028, in netCDF4._netCDF4._ensure_nc_success
RuntimeError: NetCDF: Name contains illegal characters

排查与解决步骤 #

1. 修正代码笔误 #

首先修正导入语句的错误：

import pandas as pd  # 将ad改为as

2. 修复拼接维度的错误命名 #

你在xr.concat中使用的dim=f'{["stationIDlist"]}'会生成格式错误的维度名称："['stationIDlist']"，其中包含的方括号和单引号属于NetCDF禁止的特殊字符，这是触发错误的直接原因。

修正后的拼接代码：

xarray = xr.concat([df.to_xarray() for df in dflist], dim="stationIDlist")

3. 排查DataFrame中的隐藏非法字符 #

如果修正维度后仍报错，需要全面检查相关命名：

• 检查DataFrame列名：

  print(df.columns)
  

  查看是否包含空格、特殊符号（如!@#$%^&*()）、全角字符或不可见控制字符。
• 检查DataFrame索引名：

  print(df.index.name)
  

• 检查转换后xarray的所有命名：

  print(xarray.dims)       # 打印所有维度名
  print(xarray.data_vars)  # 打印所有变量名
  print(xarray.attrs)      # 打印所有属性名
  

4. 清理非法字符 #

若发现不符合NetCDF规则的命名，用正则表达式替换清理：

# 清理列名
df.columns = df.columns.str.replace(r'[^a-zA-Z0-9_]', '_', regex=True)
# 清理索引名
if df.index.name:
    df.index.name = df.index.name.replace(r'[^a-zA-Z0-9_]', '_')
# 清理xarray的维度/变量名（若需要）
xarray = xarray.rename({k: k.replace(r'[^a-zA-Z0-9_]', '_') for k in xarray.dims})
xarray = xarray.rename({k: k.replace(r'[^a-zA-Z0-9_]', '_') for k in xarray.data_vars})

5. 牢记NetCDF命名规则 #

NetCDF对名称的硬性要求：

• 仅允许ASCII字母、数字、下划线
• 不能以数字或下划线开头
• 禁止包含空格、特殊符号、非ASCII字符

内容的提问来源于stack exchange，提问作者alecjcook