Navicat项目文件与数据库文件必须分离：/sql/存可版本控制SQL，/navicat-meta/存导出的连接和查询，系统缓存目录须.gitignore且禁提交。
Navicat 项目文件 ≠ 数据库文件，别混在同一个目录下
Navicat 本身不生成“项目文件”（如 .navicatproj 这类），它所有连接配置、查询收藏、自动化任务都存于本地应用数据目录，和你的数据库脚本（.sql）、建表语句、迁移文件完全无关。很多团队一上来就把 create_table_user.sql 和 Navicat 的临时缓存塞进同一级 /db/ 目录，结果 Git 提交时误传了二进制缓存、CI 流水线因路径冲突失败、新成员 clone 后 Navicat 自动加载了旧连接导致连错测试库——根源就是没分清“工具元数据”和“可交付代码资产”。
推荐的三层物理目录结构（含真实路径示例）
按职责隔离，不是为了好看，是为了让 CI/CD、Git、新人上手都少出错：
-
第一层：
/sql/—— 只放人工编写的、可版本控制的 SQL 资产
例如：/sql/init/（初始化脚本）、/sql/migration/（Alembic 或手动维护的 v1.2.0_add_index_to_order.sql）、/sql/dump/（仅导出的生产脱敏快照，加.gitignore） -
第二层：
/navicat-meta/—— 仅用于存放团队约定的 Navicat 导出物
例如：/navicat-meta/connections.json（用 Navicat 的「导出连接」功能生成，非必须，但比共享 .navicat 文件更安全）、/navicat-meta/queries/（高频复用的查询语句，导出为 .sql 文本，避免依赖 UI 收藏夹） -
第三层：操作系统级缓存目录（绝对不纳入 Git）
Windows：%APPDATA%\PremiumSoft\Navicat\Temp\
macOS：~/Library/Caches/com.premiumsoft.navicat/
Linux：~/.navicat/Cache/
这些路径必须写进项目根目录的.gitignore，且在 README.md 里明确标注“此目录由 Navicat 自动管理，禁止手动修改或提交”
多人协作时最常踩的三个坑
不是技术问题，是协作习惯问题：
- 有人把 Navicat 的
.nb3备份文件拖进/sql/目录并提交 —— 它是加密二进制，无法 diff，且每次打开都会变，直接导致 Git 历史污染。正确做法：备份只走运维侧统一策略，开发侧不碰.nb3。 - 不同成员 Navicat 版本不一致（比如 v16 vs v17），导出的
connections.json字段兼容性差，导入后连接名乱码或端口丢失。解决方案：团队文档中锁定 Navicat 最小支持版本，并在/navicat-meta/下加VERSION.md标明。 - 自动化任务（如定时导出）的输出路径设成相对路径，比如
./export/，结果脚本在 Jenkins 上跑时默认工作目录不是项目根，文件写到 /tmp 下再也找不到。必须用绝对路径或环境变量（如${PROJECT_ROOT}/export/），并在任务配置里显式设置“工作目录”。
真正关键的不是目录名，而是谁有权写入
大型项目里，/sql/migration/ 应该只允许 DBA 或后端主程提交；/navicat-meta/queries/ 可开放给测试同学提 PR 补充常用诊断 SQL；而所有操作系统缓存目录，必须确保 CI 流水线运行用户对该路径无写权限——否则一个失败的自动化任务可能把整个 Temp/ 塞满，拖垮构建节点。目录层级只是骨架，权限边界才是血肉。
