GIS研习社 GIS研习社
编程与开发 Git github

GitHub项目代码一团乱，GIS协作开发怎么理？（附：分支管理规范）

编程与开发
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

《GitHub项目代码一团乱，GIS协作开发怎么理？（附：分支管理规范）》这篇文章，面向的是正在做 WebGIS、Python GIS、ArcPy、PostGIS 或数据处理脚本协作的 GIS 团队。很多 GIS 项目一开始只是几个人传脚本、改配置、提交地图样式，后来代码、数据路径、分支、版本全混在一起，最后谁也不敢合并。

本文不讲抽象的 Git 理论，而是从 GIS 协作开发最常见的混乱场景出发，给出一套可以直接落地的 GitHub 分支管理规范，帮助你把项目代码、空间数据处理脚本、地图服务配置和前端 WebGIS 代码整理清楚。

GitHub项目代码一团乱 GIS协作开发分支管理规范示意图
GIS 协作开发中推荐的 GitHub 分支流转方式：功能开发、测试、发布和紧急修复分开管理。

引言：GIS 项目为什么特别容易把 GitHub 代码搞乱

普通软件项目通常只需要管理源代码，而 GIS 项目往往还包含空间数据、样式文件、坐标系说明、地图服务配置、处理脚本、前端地图页面、数据库初始化 SQL 等内容。只要缺少规范，GitHub 仓库很快就会变成“谁最后提交谁负责”的状态。

常见情况包括：

  • 同一个缓冲区分析脚本，有人改参数，有人改路径，有人改输出字段，最后互相覆盖。
  • WebGIS 前端同时改图层加载、弹窗样式和权限逻辑，合并时冲突不断。
  • PostGIS SQL 脚本没有版本号，生产库和测试库结构不一致。
  • QGIS 项目文件、符号样式、数据路径被多人改动，打开后图层丢失。
  • 所有人都直接往 main 分支提交，导致线上版本随时可能被未测试代码污染。

所以，GIS 协作开发要解决的不是“会不会用 GitHub”，而是要建立一套团队都能遵守的分支管理规范。

背景：GIS 协作开发中最常见的代码混乱类型

1. 脚本和数据路径混在一起

GIS 脚本常常依赖本地数据路径，例如 Shapefile、GeoPackage、栅格影像、CSV 坐标表等。如果开发者把本机绝对路径写进代码，再提交到 GitHub，其他人拉取后基本无法直接运行。

input_path = "D:/project/data/road.shp"
output_path = "D:/project/result/buffer.shp"

这类代码在个人电脑上能跑，在团队协作中却很危险。正确做法是使用相对路径、配置文件或环境变量。

2. 分支没有用途区分

很多团队会建立多个分支，但命名随意，例如 test、new、final、final2、zhangsan、old_backup。时间一长，没有人知道哪个分支能发布，哪个分支只是临时试验。

GIS 项目尤其容易出现这种问题，因为一个任务可能同时涉及空间分析脚本、地图样式、前端图层、服务接口和数据库结构。如果分支不清楚，合并时就很难判断影响范围。

3. 空间数据直接塞进 Git 仓库

小型 GeoJSON 或样例数据可以放入仓库，但大型影像、DEM、倾斜摄影数据、矢量切片、MBTiles、FileGDB 等不适合直接提交到 GitHub。它们会导致仓库体积暴涨，克隆速度变慢，历史版本难以清理。

4. 没有代码审查和测试流程

GIS 开发中，代码能运行不代表结果正确。比如缓冲区单位错了、坐标系没投影、ST_Intersects 查询漏建空间索引、WebGIS 图层顺序错了，都可能造成业务错误。

如果所有修改都直接合并到主分支，团队很难在发布前发现问题。

原理：GitHub 分支管理要解决什么问题

GitHub 分支管理的核心目标，是把不同阶段的代码隔离开来。对于 GIS 协作开发，可以简单理解为：

  • 稳定版本：可以部署、交付或演示的代码。
  • 开发版本：多人正在集成的新功能。
  • 功能分支：某个具体 GIS 功能或问题的开发过程。
  • 修复分支：针对线上错误或紧急问题的快速修复。
  • 实验分支：不确定是否采用的算法、样式或技术验证。

如果没有分支管理，所有内容都会挤在一个分支里。你无法判断某次提交是修复地图加载错误，还是修改了 PostGIS 表结构，也无法安全回滚。

对 GIS 项目来说，分支管理还要额外关注三件事：

  • 空间数据是否可复现：别人能否用同样脚本生成结果。
  • 坐标系和单位是否明确：尤其是面积、距离、缓冲区、叠加分析。
  • 服务和数据库是否同步：前端图层、后端接口、PostGIS 表结构必须对应。

步骤：一套适合 GIS 团队的 GitHub 分支管理规范

步骤 1：明确主分支职责

建议 GIS 项目至少保留两个长期分支：

  • main：稳定发布分支，只放已经测试通过、可以部署或交付的版本。
  • develop：日常开发集成分支，功能开发完成后先合并到这里测试。

不要让团队成员直接往 main 提交代码。main 分支应该通过 Pull Request 合并，并且最好要求至少一名成员审核。

分支 用途 是否允许直接提交
main 正式发布、交付、线上部署 不建议
develop 日常开发集成、联调测试 可限制核心成员提交
feature/* 具体功能开发 允许开发者提交
hotfix/* 线上紧急问题修复 允许指定人员提交

步骤 2：按 GIS 任务创建功能分支

功能分支不要用人名命名，而要用任务或问题命名。这样即使半年后回看，也能知道这个分支做了什么。

推荐命名方式：

feature/模块-功能
feature/webgis-layer-control
feature/postgis-road-index
feature/arcpy-batch-clip
feature/qgis-style-update
feature/geopandas-buffer-analysis

如果团队使用中文 issue，也可以在分支名中保留英文关键词，避免不同操作系统和工具对中文路径支持不一致。

步骤 3：为修复类任务单独建 hotfix 分支

GIS 项目的线上问题可能包括图层无法加载、坐标偏移、地图服务 404、空间查询结果为空、切片路径错误等。此类问题应该从 main 分支拉出 hotfix 分支，而不是从 develop 随便改。

hotfix/map-layer-404
hotfix/postgis-query-empty
hotfix/coordinate-offset
hotfix/wmts-tile-url

修复完成后，hotfix 分支需要同时合并回 main 和 develop，避免主分支修好了，但开发分支仍然保留旧问题。

步骤 4：使用 Pull Request 做代码审查

Pull Request 不只是“合并按钮”，更是 GIS 团队检查质量的入口。每个 PR 至少写清楚三件事：

  • 本次修改解决了什么问题。
  • 影响哪些模块、图层、数据表或接口。
  • 如何验证结果正确。

一个较好的 PR 描述示例：

本次修改：
1. 新增道路缓冲区分析脚本 scripts/buffer_roads.py
2. 输入数据为 data/sample/roads.gpkg
3. 输出结果为 outputs/road_buffer.gpkg
4. 坐标系要求 EPSG:3857，缓冲距离单位为米
5. 已在 QGIS 中检查缓冲区范围和字段属性

步骤 5：提交信息要能看出 GIS 修改内容

不要写“更新代码”“修改一下”“fix bug”。GIS 协作开发中，提交信息最好能说明对象和动作。

推荐格式：

类型: 修改对象 - 具体说明

示例：

fix: WebGIS图层 - 修复行政区边界加载失败
feat: PostGIS索引 - 为道路表新增GIST空间索引
refactor: ArcPy脚本 - 拆分批量裁剪与投影转换逻辑
docs: 数据说明 - 补充坐标系和字段含义
style: QGIS样式 - 调整土地利用分类配色

步骤 6：把数据、配置和代码分开管理

建议 GIS 项目采用如下目录结构：

project/
├── README.md
├── docs/
│   ├── data_dictionary.md
│   └── crs.md
├── scripts/
│   ├── arcpy/
│   ├── geopandas/
│   └── postgis/
├── web/
│   ├── src/
│   └── public/
├── config/
│   ├── config.example.yml
│   └── layers.example.json
├── data/
│   └── sample/
├── sql/
│   ├── 001_init_schema.sql
│   └── 002_add_spatial_index.sql
└── outputs/
    └── .gitkeep

其中，大型原始数据不要直接提交。可以在 README 中说明数据来源、下载地址、版本、坐标系和存放路径。

步骤 7：配置 .gitignore，避免提交无关文件

GIS 项目应特别注意忽略临时文件、输出结果、大型数据和本地配置。

# Python
__pycache__/
*.pyc
.venv/
.env

# GIS outputs
outputs/*
!outputs/.gitkeep
*.aux.xml
*.ovr
*.qix
*.lock

# Large GIS data
*.tif
*.tiff
*.img
*.mbtiles
*.gdb/
*.gpkg

# Local config
config/config.yml
config/layers.json

# QGIS temporary
*.qgz~
*.qgs~

注意：是否忽略 GeoPackage 要看项目情况。如果是小型样例数据，可以保留在 data/sample；如果是生产数据或大文件，应排除在 Git 仓库之外。

步骤 8：发布版本要打 tag

当 main 分支达到一个可交付状态时，建议创建版本标签，例如：

v1.0.0
v1.1.0
v1.1.1

GIS 项目发布说明应写清楚：

  • 新增或修改了哪些图层。
  • 涉及哪些空间数据版本。
  • PostGIS 表结构是否变化。
  • 地图服务地址或接口是否变化。
  • 是否需要重新生成缓存、切片或索引。

常见坑：GIS 协作开发中最容易忽略的问题

坑 1：把 main 当作日常开发分支

这是最常见的问题。main 一旦混入未测试代码，团队就无法判断当前版本是否稳定。正确做法是：功能先进入 feature 分支，再合并到 develop 测试，最后由负责人合并到 main。

坑 2：只提交结果，不提交处理过程

GIS 项目里，很多人习惯把处理后的 Shapefile、GeoPackage 或栅格结果提交上去，却没有提交生成过程。这样别人无法复现，也无法判断结果是否正确。

更好的方式是提交脚本、参数说明和小型样例数据。大型结果数据应放到对象存储、网盘、数据服务器或专门的数据管理系统中。

坑 3：坐标系说明缺失

如果 README、数据字典或脚本注释中没有写坐标系，后续很容易出现距离单位错误、面积不准、叠加分析错位等问题。

建议在 docs/crs.md 中至少说明：

  • 项目默认坐标系。
  • 原始数据坐标系。
  • 分析计算使用的投影坐标系。
  • 前端地图展示使用的坐标系。

坑 4：数据库脚本没有顺序

PostGIS 项目中，SQL 脚本必须有顺序。不要使用 init.sql、new.sql、update.sql 这种模糊命名。

建议使用编号：

001_init_schema.sql
002_import_boundary.sql
003_create_spatial_index.sql
004_add_landuse_field.sql

这样新成员可以按顺序初始化数据库，测试环境和生产环境也更容易保持一致。

坑 5：QGIS 项目文件路径不可迁移

QGIS 项目文件如果引用本地绝对路径，别人打开时可能全部图层丢失。建议使用相对路径，并在仓库中约定数据目录结构。

方法比较：不同规模 GIS 团队适合哪种分支策略

团队情况 推荐策略 适合场景 注意事项
1 到 2 人小项目 main + feature 课程作业、个人工具、小型脚本 也不要直接把临时实验提交到 main
3 到 8 人常规 GIS 项目 main + develop + feature + hotfix WebGIS、Python GIS、PostGIS 应用 必须通过 PR 合并关键分支
多人长期维护项目 Git Flow 或简化 Git Flow 平台型 WebGIS、企业内部系统 需要版本发布、测试和权限控制
频繁上线的 WebGIS 产品 Trunk-Based Development 加短生命周期分支 自动化测试完善、持续部署团队 对测试和代码审查要求较高

对大多数 GIS 学习团队和中小型项目来说，推荐采用简化版 Git Flow：main 保持稳定，develop 用于集成，feature 做具体任务，hotfix 修线上问题。这套方法不复杂，但足够解决大部分“GitHub 项目代码一团乱”的问题。

检查清单：合并 GIS 分支前必须确认这些事

在合并 Pull Request 前，可以按下面清单检查：

  • 分支名是否能说明具体 GIS 任务。
  • 提交信息是否说明修改对象和修改原因。
  • 是否误提交了大型空间数据、缓存文件或本地配置。
  • 脚本是否使用相对路径或配置文件。
  • 输入数据、输出结果和坐标系是否写清楚。
  • PostGIS SQL 是否有编号和执行顺序。
  • WebGIS 图层配置是否与接口、服务地址一致。
  • QGIS 项目文件是否使用相对路径。
  • 是否在本地或测试环境验证过地图显示、空间查询或分析结果。
  • 是否需要更新 README、数据字典或部署说明。

经验规则：只要某次修改会影响地图显示、空间分析结果、数据库结构或服务接口，就不要直接合并到 main。

FAQ：关于 GitHub 和 GIS 协作开发的常见问题

Q1：GIS 项目里的数据到底能不能放 GitHub？

可以放小型样例数据，例如几 KB 到几 MB 的 GeoJSON、CSV、GeoPackage 示例文件。但不建议提交大型影像、切片、FileGDB、生产数据和涉密数据。更推荐在 GitHub 中保存数据说明、下载方式、字段字典和处理脚本。

Q2：一个人做 GIS 项目还需要分支管理吗？

需要，但可以简化。一个人也建议保留 main 分支稳定版本，新功能用 feature 分支开发。这样做的好处是可以随时回到可运行状态，避免实验代码破坏已有成果。

Q3：WebGIS 前端和 PostGIS 后端要放在同一个仓库吗？

小项目可以放在同一个仓库，便于学习和联调。中大型项目建议拆分为前端仓库、后端仓库、数据库脚本仓库或使用 monorepo 统一管理。关键不是放在哪里，而是接口、图层配置、数据库变更必须有清晰说明。

Q4：QGIS 项目文件适合多人协作吗？

可以协作，但要谨慎。QGIS 项目文件中包含图层路径、样式、布局等内容，多人同时修改容易产生冲突。建议把样式文件、数据目录和项目文件结构规范好，并尽量避免多人同时改同一个 QGIS 项目文件。

Q5：GIS 脚本结果不一致，是 GitHub 分支的问题吗？

不一定。结果不一致常见原因包括坐标系不同、依赖库版本不同、输入数据版本不同、空间索引或数据库环境不同。分支管理能帮助你追踪代码变化，但还需要配合 README、requirements.txt、环境说明和数据版本记录。

Q6：分支越多是不是越规范？

不是。分支管理的目标是降低混乱，而不是制造更多流程。对于大多数 GIS 团队，main、develop、feature、hotfix 已经足够。过多长期分支如果没有维护规则，反而会增加合并成本。

结论：GIS 协作开发的关键不是多建分支，而是让每次修改可追踪、可验证、可回滚

GitHub 项目代码一团乱，通常不是工具问题，而是缺少统一的协作规则。对于 GIS 项目来说，分支管理规范要同时考虑代码、空间数据、坐标系、数据库、地图服务和前端图层配置。

建议从最小规范开始落地：

  • main 只保留稳定版本。
  • develop 用于日常集成测试。
  • 每个 GIS 功能单独创建 feature 分支。
  • 线上问题使用 hotfix 分支修复。
  • 通过 Pull Request 合并关键修改。
  • 大型数据不直接提交，坐标系和数据版本必须说明。

当团队能做到这些，GIS 协作开发就会从“谁也不敢合并”变成“每次修改都知道影响哪里”。这比单纯学习几个 Git 命令更重要，也更适合真实的 GIS 项目交付。