用途:该技能面向 QGIS/PyQGIS 数据加载故障排查,适用于图层无效、加载后要素为空、属性乱码、数据库锁定、PostGIS/WMS/WFS 连接失败、大数据集卡顿、坐标系缺失及 Shapefile 限制等场景。核心规则是创建任何图层后立即调用 layer.isValid(),因为无效图层不会抛出异常,而是返回崩溃或行为未定义的坏对象;切勿在无效图层上访问要素、属性或数据源方法。
主要能力按错误类别组织:E-001 无效图层,依次核查文件路径、provider 名称、凭证、CRS 数据库与文件完整性,并通过 dataProvider().error().message() 查看详情;E-002 URI 格式错误,分 provider 给出正确写法(如 GeoPackage 需 |layername=,PostGIS 用 QgsDataSourceUri,WMS 需 url= 等);E-003 Shapefile 的 .dbf 编码乱码,可用 URI 的 option:ENCODING、.cpg 文件或 setEncoding() 处理;E-004 GeoPackage 的 SQLite 写入锁冲突,可通过 WAL、检查 -wal/-shm/-journal 锁文件、关闭其他进程或改用 PostGIS 缓解;E-005 PostGIS 连接失败,按网络、认证、库、schema/表、几何列、主键逐项排查,生产环境应使用 QgsAuthManager 而非明文密码;E-006 WMS/WFS 与 XYZ 瓦片超时或能力解析失败,需核对 URL、图层名、CRS 及占位符 URL 编码;E-007 大数据集性能,使用 QgsFeatureRequest 的空间/属性过滤、子集属性、NoGeometry 与 setLimit() 避免一次性载入全部要素;E-008 CRS 缺失,用 setCrs() 仅设元数据,重投影需用处理算法或坐标变换;E-009 Shapefile 固有限制,如字段名 10 字符、2GB 上限、无 NULL 与日期时间精度,建议迁移至 GeoPackage。
使用方式:提供诊断流程图和修复模式总表,先判断文件/服务是否存在,再判断 isValid()、要素数量、位置、属性与性能。参考文件包括 methods.md、examples.md、anti-patterns.md。限制:资料未提供安装步骤、价格与平台要求;仅涉及 QGIS/PyQGIS 数据加载相关错误。