离线地图集成故障求助：MBTiles与PNG瓦片均无法加载

问题情况 #

加载离线地图瓦片时失败，尝试MBTiles文件和PNG图片两种方式均未成功，核心代码如下：

@override
Widget build(BuildContext context) {
  return Scaffold(
    appBar: AppBar(title: const Text('Offline Map')),
    drawer: buildDrawer(context, route),
    body: Padding(
      padding: const EdgeInsets.all(8),
      child: Column(
        children: [
          const Padding(
            padding: EdgeInsets.only(top: 8, bottom: 8),
            child: Text(
                'This is an offline map that is showing Anholt Island, Denmark.'),
          ),
          Flexible(
            child: FlutterMap(
              options: MapOptions(
                initialCenter: const LatLng(56.704173, 11.543808),
                minZoom: 12,
                maxZoom: 14,
                cameraConstraint: CameraConstraint.containCenter(
                  bounds: LatLngBounds(
                    const LatLng(56.7378, 11.6644),
                    const LatLng(56.6877, 11.5089),
                  ),
                ),
              ),
              children: [
                TileLayer(
                  tileProvider: AssetTileProvider(),
                  maxZoom: 14,
                  urlTemplate: 'assets/map/anholt_osmbright/{z}/{x}/{y}.png',
                ),
              ],
            ),
          ),
        ],
      ),
    ),
  );
}

报错信息：

flutter: Unable to load asset: "assets/map/anholt_osmbright/12/2046/1361.png".
flutter: Unable to load asset: "assets/map/anholt_osmbright/12/2047/1360.png".
flutter: Exception: Asset not found
flutter: Unable to load asset: "assets/map/anholt_osmbright/12/2045/1363.png".
flutter: Exception: Asset not found
flutter: Unable to load asset: "assets/map/anholt_osmbright/12/2047/1363.png".
flutter: Exception: Asset not found

排查与解决步骤 #

1. 确认pubspec.yaml的资源注册 #

Flutter必须在pubspec.yaml中声明要使用的资源，确保添加了正确的路径：

flutter:
  assets:
    - assets/map/anholt_osmbright/
    # 若存在多层子目录，用通配符覆盖所有文件
    - assets/map/anholt_osmbright/**

修改后执行flutter pub get刷新资源配置。

2. 验证瓦片坐标格式匹配 #

地图瓦片的Y轴存在OSM（默认）和TMS两种常用格式，如果你的瓦片是TMS格式，Y轴坐标会和FlutterMap默认的OSM格式相反，导致找不到文件。
解决方案：在TileLayer中指定坐标系统为TMS：

TileLayer(
  tileProvider: AssetTileProvider(),
  maxZoom: 14,
  urlTemplate: 'assets/map/anholt_osmbright/{z}/{x}/{y}.png',
  tileCoordinateSystem: TileCoordinateSystem.tms, // 添加该行配置
),

3. 检查文件路径与大小写 #

• 确认本地文件系统中，assets/map/anholt_osmbright/12/下确实存在报错中提到的文件（如2046/1361.png）。
• 注意iOS系统区分文件名大小写，Android不区分，需确保代码中的路径和实际文件的大小写完全一致。

4. 清理Flutter缓存 #

资源缓存可能导致加载异常，执行以下命令后重启项目：

flutter clean
flutter pub get

5. MBTiles文件加载注意事项 #

如果使用MBTiles格式，需使用对应的瓦片提供者：

1. 添加依赖到pubspec.yaml：

dependencies:
  flutter_map_mbtiles: ^最新版本号

2. 修改TileLayer代码：

TileLayer(
  tileProvider: MbTilesTileProvider(
    databaseName: 'anholt.mbtiles', // 确保该文件已在pubspec.yaml中注册
  ),
  maxZoom: 14,
  urlTemplate: '', // MBTiles无需配置urlTemplate
),

同时确保MBTiles文件已在pubspec.yaml的assets中注册。

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