1

开发指南 5 子模块更新

SkyLi edited this page 2026-04-14 09:46:10 +08:00

Table of Contents

• 子模块更新说明
• 工作流程图
• 子模块独立开发的好处
• 推荐做法
• 常见问题
• Q: 克隆时提示 Permission denied (publickey)？
• Q: 子模块目录是空的？
• Q: 如何查看子模块的远程地址？
• Q: 能否在主仓库目录内直接操作子模块？
• Q: 推送代码时需要同时推送主仓库和子模块吗？

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

子模块更新说明

本文介绍子模块的独立开发模式及推荐工作流程。

工作流程图

┌─────────────────────────────────────────────────────────────┐
│                     主仓库 (main)                           │
│   仅记录子模块指针，不频繁更新（仅大版本/发布前更新）          │
└─────────────────────────────────────────────────────────────┘
        ▲               ▲               ▲
        │               │               │
        │  submodule    │  submodule    │  submodule
        │  update       │  update       │  update
        │  --remote     │  --remote     │  --remote
        │               │               │
┌───────────┐     ┌───────────┐     ┌───────────┐
│  chassis  │     │   gimbal  │     │  其他模块  │
│ (子模块)   │     │ (子模块)   │     │ (子模块)   │
│ 独立分支   │     │ 独立分支   │     │ 独立分支   │
│ 独立PR    │     │ 独立PR    │     │ 独立PR    │
└───────────┘     └───────────┘     └───────────┘

子模块独立开发的好处

• 各模块可以独立迭代，不影响其他模块
• 子模块的 PR 不会触发主仓库不必要的构建
• 团队可以并行开发多个功能

推荐做法

场景	操作位置
修改 modules/chassis 代码	在 modules/chassis 目录内创建分支、提 PR
修改 modules/gimbal 代码	在 modules/gimbal 目录内创建分支、提 PR
修改主仓库配置/文档	在主仓库创建分支、提 PR
更新子模块指针（仅大版本）	在主仓库创建分支、提 PR

---

常见问题

Q: 克隆时提示 Permission denied (publickey)？

检查：

1. 公钥是否正确添加到 Gitea
2. 私钥文件是否存在且权限正确（chmod 600 ~/.ssh/id_ed25519）
3. SSH 代理是否加载了私钥

Q: 子模块目录是空的？

使用了 git clone 但没有加 --recursive，或子模块未初始化。运行：

git submodule update --init --recursive

Q: 如何查看子模块的远程地址？

git submodule foreach 'git remote -v'

Q: 能否在主仓库目录内直接操作子模块？

可以，使用 git -C 语法：

git -C modules/chassis status
git -C modules/chassis checkout main
git -C modules/chassis pull origin main

这与先 cd 再执行效果相同。

Q: 推送代码时需要同时推送主仓库和子模块吗？

不需要。子模块和主仓库是独立的仓库，各自有独立的提交历史和分支体系。

• 在子模块中开发 → 在子模块仓库提 PR → 合并到子模块的 main
• 在主仓库修改配置文件/文档 → 在主仓库提 PR → 合并到主仓库的 main

只有当你确实需要将子模块的指针更新同步给其他成员时，才需要更新并推送主仓库（如第 4 节所述的大版本场景）。

导航

开发入门

• 开发指南-1-SSH密钥配置
• 开发指南-2-连接验证
• 开发指南-3-仓库拉取
• 开发指南-4-开发流程
• 开发指南-5-子模块更新

技术文档

• 硬件技术参数
• 硬件相关外链

设计方案

• 底盘设计方案
• 云台视觉设计方案

Footer