STAC 的检索接口能返回 item，并不表示用户已经能可靠地看见遥感资产。浏览器地图还要处理 COG 像元、Web map service 图层、上传的表格化空间文件以及搜索状态；任何一处把来源、投影、网络请求或文件范围藏起来，地图就可能显示“看起来合理”的错误图像。Development Seed 的开源 stac-map 将这些能力放到一个 map-first、单页、静态托管的 STAC 可视化器中：浏览器端 COG 渲染、Web map service 显示、stac-geoparquet 的可视化/上传/导出，以及可复用的 React component。

它适合用作上线验收的参考对象，而不是把静态站点误读成无需治理的数据入口。若 GIS 团队采用类似架构，应将“这个像素来自哪里、这个服务图层如何请求、这个用户文件怎样留在浏览器或离开浏览器”写成可检查的边界。

可核查事实

  • stac-map 的官方 README 将项目定义为 map-first、single-page、statically-hosted 的 STAC visualizer，公开演示地址为 developmentseed.org/stac-map。

  • README 列出 browser client-side COG rendering，并明确使用 deck.gl-raster。

  • README 支持 Web map service display。

  • README 列出 stac-geoparquet 的 visualization、upload 与 export 能力。

  • 项目说明提供 React component，供其他应用复用。

  • 本地开发说明使用 yarn：clone 后运行 yarn install 与 yarn dev，开发服务器地址为 http://localhost:5173/stac-map/。

  • README 列出 yarn lint、yarn format，以及安装 Playwright 后运行 yarn test 的质量检查路径。

  • 项目使用 GitHub Pull Request 提交变更与 issue 跟踪问题，并以 release-please 创建 release，提交消息遵循 Conventional Commits。

这些事实界定了它的实现方向：可视化逻辑首先运行在浏览器，站点可以静态托管，但数据来源、服务请求与用户文件仍然具有需要治理的生命周期。

核心机制

STAC 地图的可追溯性至少由四个对象构成。第一是 catalog/item：搜索条件、collection、时间、空间范围与 asset href 决定候选数据。第二是像素或服务层：COG 的浏览器请求、Web map service 的 URL 与参数、渲染所用的波段/样式决定地图显示。第三是本地文件：GeoParquet 的上传、读取、导出和清理路径决定用户数据是否离开设备。第四是应用版本：前端构建、组件版本和地图配置决定同一 item 在未来能否重现。

静态托管只说明 HTML、JavaScript 和样式可以作为静态文件部署；它不让外部 COG、WMS 或 STAC API 自动变得可靠、安全或可复现。浏览器端渲染意味着请求可能直接从用户网络发出，受到 CORS、鉴权、对象存储可用性、投影解释与客户端内存限制影响。因此，一个可发布的地图视图必须保存其来源合同，而不仅是截图。

GIS 场景

以灾后影像核查为例，分析人员用 bbox、日期和 collection 搜索 STAC，再在地图中打开一份 COG。系统应把查询 JSON、STAC item ID、asset href、ETag 或版本标识、渲染波段、色带、nodata、缩放级别和地图中心记录为可分享视图。查看者若看到“受损区域”，才能知道该结论来自哪一时相、哪个资产和哪一套显示参数；不能把浏览器缓存里的当前画面当作数据版本证据。

若用户上传 stac-geoparquet 来叠加资产清单，首先要向用户说明文件会在何处解析、是否上传到服务器、是否可被其他会话访问、导出包含哪些字段。即便应用是静态托管，某些部署也可能附加分析 API、遥测或上传代理。隐私敏感的 AOI、资产 URL、采集时间或业务字段应经过最小化处理；导出前复核 CRS、geometry 编码、字段选择和许可，避免把临时可视化变成未经审查的数据分发。

技术路径

为每次可分享地图生成一个最小 manifest：应用 release/commit、STAC endpoint、查询 JSON、item/asset ID、asset 版本或校验信息、渲染器类型、波段/表达式、色带、nodata、CRS、view state 和生成时间。打开页面时先验证 manifest 能重新解析 item；若 asset 已下线、CORS 失败或版本改变，明确标示“不可复现”，不要静默显示最近的缓存结果。

将图层按网络模型分开测试。对 browser-side COG，测试跨域响应、range request、像元范围、band 选择、nodata 和大 AOI 的内存预算；对 Web map service，固定 service URL、layer、style、CRS、bbox、format、time 与认证方式，并保存一次请求样本。两类图层都应有离线模拟或失败 UI：数据服务不可用时显示来源和错误类别，而不是用空白图或旧瓦片暗示正常。

对 stac-geoparquet 设置文件合同：允许的文件大小、geometry/CRS、必需和禁止字段、是否只在本地解析、导出的落点与自动清理时间。导入后抽样验证行数、geometry 有效性、空间范围和字段类型；导出前加入数据集版本、查询范围和许可提示。React component 若被嵌入其他系统，应由宿主显式传递 endpoint、鉴权和日志策略，不让组件默认继承未知的全局配置。

风险边界

README 的功能清单不保证任意 COG、WMS、STAC API 或 GeoParquet 文件都能在所有浏览器和网络下正常工作。客户端 COG 渲染不替代服务端瓦片缓存、访问控制或大规模计算；Web map service 的视觉结果也不证明其时相、坐标或样式符合分析口径。stac-geoparquet 的 upload/export 功能不能自行决定数据分类、许可或保留期。开源项目的 lint、format 与测试命令是维护路径，不是对私有部署的安全或性能认证。

检查清单

  1. 为每个分享视图保存 STAC 查询、item/asset ID、版本信息、渲染参数、CRS 和 view state。

  2. 分别验收 COG 的跨域/range 请求、band/nodata/内存边界，与 WMS 的 layer/style/CRS/bbox/time 参数。

  3. 在数据源失败、asset 版本变化和 CORS 拒绝时显示可诊断状态，禁止静默回退旧缓存。

  4. 为 stac-geoparquet 定义文件大小、geometry、CRS、字段、处理位置、导出位置和清理期限。

  5. 导入和导出时抽样核对行数、有效几何、范围、字段类型、版本和许可。

  6. 嵌入 React component 时显式传入 endpoint、授权与日志策略，避免依赖未知全局状态。

  7. 对可见结论保留像素/服务来源和显示参数；截图不能替代 manifest。

结论

stac-map 说明 STAC 可视化可以保持前端轻量和静态托管，但可信地图仍要把搜索、资产、渲染、服务请求和文件处理一起记录。先验收这些边界，再把地图分享给决策者，才能让浏览器中的遥感图层既可看见，也可追溯。

参考来源

  1. Development Seed stac-map 官方 README：https://github.com/developmentseed/stac-map