城乡规划GIS项目迁移Git遇阻？Gitee平台代码协同避坑指南（含：操作要点）
引言
“城乡规划GIS项目迁移Git遇阻？Gitee平台代码协同避坑指南（含：操作要点）”这个问题，通常不是单纯的 Git 命令不会用，而是城乡规划GIS项目里同时包含代码、地图样式、空间数据、配置文件、脚本工具和多人协作流程，一旦迁移到 Gitee，就容易遇到大文件推送失败、坐标数据误传、分支混乱、历史记录过大、密钥泄露等问题。
本文面向 GIS 学生、规划院项目组、WebGIS 开发人员和初级 GIS 工程师，重点讲清楚：城乡规划GIS项目如何从本地 Git 或其他平台迁移到 Gitee，哪些文件适合进仓库，哪些空间数据不该直接提交，以及多人协同时如何设置分支、权限和提交规范。
背景
城乡规划GIS项目与普通软件项目不同。一个项目目录里可能同时存在 ArcGIS Pro 工程文件、QGIS 工程文件、Python 批处理脚本、WebGIS 前端代码、GeoJSON、Shapefile、影像切片、规划成果图、空间数据库连接配置等内容。
很多团队在迁移 Git 到 Gitee 时，会直接执行：
git remote add origin https://gitee.com/your-team/your-gis-project.git
git push -u origin master看起来简单，但在实际城乡规划GIS项目中，常见问题包括：
- 仓库体积过大，推送速度很慢，甚至直接失败。
- 把临时成果、影像、切片缓存、导出图件全部提交进 Git。
- 把数据库账号、PostGIS 连接串、服务器地址写进配置文件并推送到远程。
- 多人同时修改同一个 QGIS 工程文件或配置文件，产生难以合并的冲突。
- 分支没有约束，正式成果、测试代码和个人实验混在一起。
- 迁移后历史提交里仍然保留了敏感文件，即使删除也可能被追溯。
因此，城乡规划GIS项目迁移 Git 到 Gitee 的核心，不是“把所有文件推上去”，而是“把可协作、可追踪、可复现的内容放进仓库，把大数据和敏感配置从仓库中剥离”。
原理
Git 擅长管理文本型文件，例如 Python 脚本、JavaScript 代码、SQL 脚本、QGIS 样式文件、README 文档、配置模板等。它不擅长频繁管理大型二进制文件，例如遥感影像、MBTiles、文件地理数据库、压缩包、CAD 成果包、大型 Shapefile 和切片缓存。
Gitee 是国内常用的 Git 托管平台，适合团队进行代码托管、权限控制、Issue 管理、Pull Request 协作和版本发布。但 Gitee 并不会自动帮你判断哪些 GIS 文件应该入库，哪些文件不应该入库。
对城乡规划GIS项目来说，建议将项目内容分成四类：
| 内容类型 | 是否建议提交 Git | 说明 |
|---|---|---|
| 代码与脚本 | 建议 | 如 Python、ArcPy、GeoPandas、WebGIS 前端、SQL 脚本，适合版本管理。 |
| 工程配置 | 部分建议 | 如 QGIS .qgz、样式 .qml、项目配置模板可提交，但敏感路径和账号要剥离。 |
| 空间数据 | 谨慎 | 小型示例数据可以提交，大型生产数据建议放对象存储、文件服务器或数据库。 |
| 成果与缓存 | 通常不建议 | 如导出 PDF、PNG 图件、瓦片缓存、临时分析结果，应通过发布目录或归档系统管理。 |
理解这个边界后，再做 Gitee 平台代码协同，就能避免把 Git 仓库变成“网盘式项目文件夹”。
步骤
步骤一：迁移前先清点城乡规划GIS项目目录
不要一上来就推送。先在本地项目根目录做一次文件清点，明确哪些内容是代码，哪些是数据，哪些是临时文件。
一个常见的城乡规划GIS项目目录可能是这样：
urban-planning-gis/
├── app/ # WebGIS前端或后端代码
├── scripts/ # Python、ArcPy、GeoPandas脚本
├── sql/ # PostGIS建表、索引、查询脚本
├── qgis/ # QGIS工程、样式、布局模板
├── docs/ # 项目说明、操作手册
├── sample_data/ # 小型示例数据
├── data/ # 生产空间数据，不建议直接入库
├── output/ # 分析成果和导出图件，不建议入库
├── cache/ # 切片、临时缓存，不建议入库
└── config/ # 配置文件，需要区分模板和真实配置建议保留进 Git 的内容：
- 可重复运行的处理脚本。
- WebGIS 前后端源代码。
- PostGIS 建库、建表、空间索引和视图 SQL。
- QGIS 样式文件、布局模板、少量示例工程。
- 项目说明文档、字段字典、数据处理流程说明。
- 小型脱敏样例数据，用于演示和测试。
建议排除的内容：
- 原始影像、DEM、大范围地形数据。
- 大体积 Shapefile、FileGDB、GeoPackage 生产数据。
- 切片缓存、临时中间结果、导出图件。
- 含账号密码的真实配置文件。
- 个人电脑路径、软件缓存、IDE 配置。
步骤二：编写适合 GIS 项目的 .gitignore
.gitignore 用来告诉 Git 哪些文件不要纳入版本管理。城乡规划GIS项目迁移 Git 到 Gitee 前，一定要先配置它。
# 系统与编辑器文件
.DS_Store
Thumbs.db
.vscode/
.idea/
# Python环境与缓存
__pycache__/
*.pyc
.venv/
venv/
.env
# GIS临时文件与锁文件
*.lock
*.tmp
*.aux.xml
*.qgs~
*.qgz~
*.sbn
*.sbx
# 大型空间数据目录
data/
raw_data/
raster/
tiles/
cache/
output/
exports/
# 常见大文件格式
*.tif
*.tiff
*.img
*.mbtiles
*.gpkg
*.gdb/
*.zip
*.7z
*.rar
# 敏感配置
config/local.json
config/prod.json
*.pem
*.key需要注意，.gitignore 只能忽略尚未被 Git 跟踪的文件。如果某个敏感配置或大文件已经提交过，仅仅写入 .gitignore 并不能从历史记录中删除它。
步骤三：建立配置模板，避免敏感信息进仓库
很多 GIS 项目需要连接 PostGIS、GeoServer、ArcGIS Server、对象存储或内网服务。不要把真实账号密码写入仓库。推荐做法是提交模板文件，不提交本地真实配置。
例如提交：
config/config.example.json内容可以写成：
{
"postgis_host": "127.0.0.1",
"postgis_port": 5432,
"postgis_database": "planning_gis",
"postgis_user": "your_user",
"postgis_password": "your_password",
"geoserver_url": "http://localhost:8080/geoserver"
}然后让每个成员在本地复制一份：
cp config/config.example.json config/local.json并确保真实配置文件已经写入 .gitignore：
config/local.json
config/prod.json
.env步骤四：初始化本地 Git 仓库并检查待提交文件
在项目根目录执行：
git init
git status不要急着 add 全部文件。先查看 Git 识别到了哪些文件。如果发现 data、output、cache 或真实配置文件出现在待提交列表中，说明 .gitignore 还没有配置好。
确认无误后再提交：
git add .
git commit -m "init urban planning gis project structure"提交信息建议用简单清晰的英文或中文，例如：
- init project structure
- add postgis schema scripts
- update qgis layout template
- fix geojson coordinate transform bug
- 新增控规地块入库脚本
步骤五：在 Gitee 创建远程仓库
在 Gitee 中创建仓库时，建议注意以下设置：
- 仓库名称使用简洁英文或拼音，例如 urban-planning-gis。
- 如果项目含内部规划资料，仓库应设为私有。
- 不要在 Gitee 页面自动初始化 README，以免与本地首次提交冲突。
- 为团队成员分配合适权限，不要所有人都设为管理员。
创建完成后，将远程地址添加到本地：
git remote add origin https://gitee.com/your-org/urban-planning-gis.git
git branch -M main
git push -u origin main如果团队使用 SSH，也可以使用：
git remote add origin git@gitee.com:your-org/urban-planning-gis.git
git push -u origin main步骤六：迁移已有 Git 仓库到 Gitee
如果原来已经有 Git 仓库，只是要迁移到 Gitee，可以先查看原远程地址：
git remote -v然后替换为 Gitee 地址：
git remote set-url origin https://gitee.com/your-org/urban-planning-gis.git
git push -u origin main如果需要把所有分支和标签一起迁移：
git push --all origin
git push --tags origin但在执行全量迁移前，建议先清理大文件和敏感文件。否则问题会被完整带到 Gitee。
步骤七：为城乡规划GIS项目设计分支协作规则
多人协作时，建议至少保留三个层级：
| 分支 | 用途 | 权限建议 |
|---|---|---|
| main | 稳定版本、阶段成果、可交付代码 | 限制直接推送，通过合并请求进入 |
| dev | 日常集成开发 | 核心成员维护 |
| feature/xxx | 个人功能开发或数据处理任务 | 成员自行创建，完成后合并 |
示例流程：
git checkout dev
git pull
git checkout -b feature/parcel-import
# 修改入库脚本或字段映射
git add scripts/import_parcel.py sql/parcel_schema.sql
git commit -m "add parcel import workflow"
git push -u origin feature/parcel-import然后在 Gitee 上发起 Pull Request 或合并请求，由项目负责人审核后合并到 dev，再在阶段稳定后合并到 main。
步骤八：把空间数据管理从 Git 中拆出来
城乡规划GIS项目迁移 Git 到 Gitee 时，最容易踩的坑就是把空间数据也当成代码管理。实际项目中，更推荐以下组合：
- 代码、脚本、SQL、样式、文档放 Gitee。
- 生产数据放 PostGIS、文件服务器、对象存储或专门的数据目录。
- 仓库中只保留 sample_data，用于说明字段结构和运行示例。
- 数据版本变化通过数据字典、更新日志或数据库迁移脚本记录。
例如可以在 README 中写清楚数据获取方式：
数据说明：
1. sample_data/ 仅用于本地测试，不代表完整生产数据。
2. 生产地块数据存储在 PostGIS: planning.parcel。
3. 原始CAD、影像和成果图件请从项目文件服务器获取。
4. 如需更新数据库结构，请提交 sql/migrations/ 下的 SQL 脚本。常见坑
坑一：Shapefile 只提交了一个 .shp 文件
Shapefile 不是单文件格式。一个完整图层通常至少包含 .shp、.shx、.dbf，有时还包括 .prj、.cpg 等文件。如果只提交 .shp，别人拉取后无法正常打开属性表或坐标系。
如果确实需要提交小型示例 Shapefile，必须成组提交相关文件。更推荐把示例数据转换为 GeoPackage 或 GeoJSON，并控制文件体积。
坑二：把坐标系错误当成代码错误
多人协作时，常见现象是某个成员运行脚本后，数据出现在错误位置。原因可能不是 Git 迁移失败，而是本地数据坐标系、EPSG 编码或 .prj 文件不同。
建议在 README 或 docs 中明确：
- 项目统一使用的坐标系。
- 输入数据坐标系检查方法。
- 输出成果坐标系要求。
- 是否允许自动重投影。
坑三：QGIS 工程文件多人同时改，冲突难处理
QGIS 的 .qgz 是压缩格式，不适合多人同时编辑后再合并。即使使用 .qgs XML 文件，冲突也不一定容易人工处理。
更稳妥的做法是：
- 把 QGIS 工程作为模板或阶段成果管理。
- 样式尽量拆成 .qml 或 .sld 文件单独管理。
- 多人修改前先约定负责范围，例如一个人改图层样式，一个人改布局模板。
- 重要工程文件修改前先拉取最新版本。
坑四：删除敏感文件后以为就安全了
如果数据库密码、内网地址或密钥已经提交到 Git 历史中，即使后续删除，历史提交中仍可能存在。正确处理方式是：
- 立即更换泄露的密码或密钥。
- 清理 Git 历史中的敏感文件。
- 强制推送前通知团队重新克隆或重置仓库。
- 在 Gitee 上检查历史记录和分支中是否仍可查看。
如果不熟悉历史清理，建议先备份仓库，再由熟悉 Git 的成员操作，避免误删有效提交。
坑五：所有成员都直接推 main 分支
这会导致主分支经常处于不可运行状态。尤其是城乡规划GIS项目中，脚本、SQL、样式和前端页面互相依赖，一个未测试的提交可能影响整个演示系统。
建议在 Gitee 中开启分支保护，让 main 分支只能通过合并请求更新。
方法比较
不同团队可以根据项目规模选择不同的 Gitee 协同方式。
| 方式 | 适用场景 | 优点 | 风险 |
|---|---|---|---|
| 单 main 分支 | 个人学习、小型课程作业 | 简单，学习成本低 | 多人协作容易互相覆盖 |
| main + dev | 小型规划GIS工具开发 | 能区分稳定版和开发版 | 功能任务多时仍会拥挤 |
| main + dev + feature | 多人城乡规划GIS项目 | 适合功能开发、脚本处理、WebGIS协作 | 需要成员遵守分支规范 |
| Git 管代码 + 数据库管数据 | 真实生产项目 | 仓库轻量，数据安全性更好 | 需要额外维护数据说明和权限 |
| Git LFS 管大文件 | 少量必须版本化的大文件 | 可追踪大文件版本 | 仍需关注平台限制和团队配置成本 |
对大多数城乡规划GIS项目，推荐使用“Gitee 管代码与流程，PostGIS 或文件服务器管生产数据”的方式。这样既能发挥 Git 的版本控制优势，又不会让仓库被空间数据拖垮。
检查清单
迁移到 Gitee 前，可以按下面清单逐项检查。
- 是否已经区分代码、工程、样例数据、生产数据、成果输出？
- 是否已经编写适合 GIS 项目的 .gitignore？
- data、output、cache、tiles 等目录是否已被排除？
- 是否检查过真实数据库密码、Token、密钥没有进入仓库？
- 是否提供 config.example.json 或 .env.example？
- 是否明确项目统一坐标系和数据来源？
- 是否只提交小型、脱敏、可公开的 sample_data？
- 是否为 main 分支设置保护规则？
- 是否约定 dev 和 feature 分支的使用方式？
- 是否在 README 中写明项目启动、数据准备和脚本运行步骤？
- 是否为 PostGIS 表结构变更保留 SQL 迁移脚本？
- 是否避免多人同时修改同一个 QGIS 工程文件？
FAQ
城乡规划GIS项目迁移 Git 到 Gitee 时，空间数据到底能不能提交？
可以提交少量脱敏示例数据，但不建议提交完整生产数据。生产级 Shapefile、GeoPackage、影像、切片和成果图件通常体积大、更新频繁，还可能涉及数据安全，建议放在 PostGIS、文件服务器或对象存储中。
Gitee 平台代码协同适合 QGIS 项目吗？
适合管理 QGIS 相关脚本、样式、配置模板、说明文档和少量工程模板。但 QGIS 工程文件不适合多人同时修改后自动合并，团队应提前约定编辑范围，避免冲突。
已经把大文件推到 Gitee 了怎么办？
如果只是最新提交中出现，可以先从 Git 跟踪中移除，再提交 .gitignore。若大文件已经进入多次历史提交，需要清理 Git 历史。操作前请备份仓库，并通知团队成员，避免后续拉取和推送出现混乱。
城乡规划GIS项目应该用 HTTPS 还是 SSH 连接 Gitee？
个人学习或临时项目使用 HTTPS 更容易上手。长期团队项目建议使用 SSH，并为成员配置独立密钥，便于身份管理和权限控制。无论使用哪种方式，都不要把账号密码写入项目配置文件。
WebGIS 前端代码和 PostGIS SQL 能放在同一个仓库吗？
可以，特别是在中小型项目中，把前端代码、后端接口、SQL 初始化脚本和数据处理脚本放在同一仓库有利于复现。但如果团队规模较大，也可以拆分为前端仓库、后端仓库和数据处理仓库。
如何让新成员快速接手 Gitee 上的 GIS 项目？
最有效的方法是写好 README。至少包括项目用途、目录结构、环境依赖、数据获取方式、坐标系说明、配置文件创建方式、启动命令、常见问题和分支协作规则。不要只把代码推上去而没有说明。
结论
城乡规划GIS项目迁移 Git 到 Gitee，重点不是把所有项目文件搬到远程仓库，而是建立一套可维护的代码协同规则。代码、脚本、SQL、样式和文档适合进入 Gitee；大型空间数据、成果图件、缓存和敏感配置应从仓库中剥离。
如果你正在做城乡规划GIS项目协作，建议先完成三件事：整理目录结构，写好 .gitignore，明确分支和数据管理规则。这样迁移到 Gitee 后，团队成员才能稳定拉取、提交、审核和发布，而不是在大文件、冲突和配置泄露中反复返工。