git subtree pull 拉不到最新公共组件，根本原因是本地 remote 未同步远程分支更新；需先执行 git fetch library 再 pull，否则仍基于旧 ref 操作，且分支名错误或不存在时会静默失败。

git subtree pull 为什么拉不到最新公共组件？

常见现象是执行 git subtree pull --prefix=src/library library dev --squash 后，src/library 目录内容没变，甚至提示 “Already up to date”。这不是命令失效，而是本地 library remote 指向的 ref（分支或 commit）没更新。

根本原因是：git remote add -f library <url></url> 中的 -f 只在添加时 fetch 一次，后续远程 dev 分支有新提交，本地 remote 不会自动同步 HEAD。下次 pull 仍基于旧的远程引用。

• 执行前先手动同步远程引用：git fetch library
• 再运行 pull 命令，确保它读取的是最新 library/dev
• 如果远程分支已重命名为 main，但命令里还写 dev，就会静默失败——git subtree pull 不报错，只跳过
• 用 git ls-remote library dev 可验证该分支是否存在、最新 commit hash 是什么

git subtree push 失败：Permission denied 或 non-fast-forward

推送失败通常不是权限配置问题，而是本地 subtree 提交历史与上游不一致。典型错误信息如：! [rejected] dev -> dev (non-fast-forward)，或 SSH 报 Permission denied (publickey)。

前端美化

使用此技能可创建独具特色、具备生产级质量的前端界面，设计品质高。当用户要求构建网页组件、页面、产物、海报或应用程序时（例如：网站、落地页、仪表盘、React 组件、HTML/CSS 布局，或对任意 Web UI 进行样式优化与视觉美化），请启用该能力。输出需为富有创意、精雕细琢的代码与 UI 设计，避免千篇一律的 AI 风格。

下载

• Permission denied：检查是否用了正确的 SSH key，且该 key 已添加到 Git 服务（GitLab/GitHub）账户；别名 library 对应的 URL 必须是 SSH 地址（git@gitlab.com:xxx.git），不能是 HTTPS
• non-fast-forward：说明上游 dev 分支已有别人推送的新 commit，而你的本地 subtree 提交基于更老的 base。此时不能直接 push，需先 git subtree pull --prefix=src/library library dev --squash 合并上游变更，解决冲突后再 push
• 避免多人同时向同一 subtree prefix 推送：subtree 不是为高并发协作设计的，建议约定“谁改谁推”，或把修改集中到一个负责人

–squash 到底要不要加？

--squash 不是可选项，而是微前端场景下的强烈推荐项。它决定你是否要继承上游仓库的全部提交历史。

• 加 --squash：每次 pull 只生成一条新 commit，内容是上游 diff 的合集。主仓库历史干净，git log 不被子项目几百条提交淹没；适合 UI 组件库这类“只消费不追溯”的场景
• 不加 --squash：完整导入上游所有 commit，主仓库历史里混入大量 web-common@abc123 式提交。调试时 git blame 会跳转到子项目，但实际开发中几乎没人真去翻那几百个 commit
• push 时永远不要加 --squash：否则上游仓库收不到你的真实修改记录，只剩一条“merged from project-X”空洞提交

如何安全地重构 subtree 目录结构？

比如要把 src/library 改成 libs/common，不能直接 mv + commit。git subtree 会丢失路径映射关系，后续 pull/push 全部失效。

• 先用 git subtree split --prefix=src/library --branch=library-migrate 把当前 subtree 内容导出为独立分支
• 新建空分支，把导出内容移到新路径：git checkout --orphan libs-common-migrate && git read-tree --prefix=libs/common -u library-migrate && git commit -m "move library to libs/common"
• 用新路径重新 add：git subtree add --prefix=libs/common <url><ref> --squash</ref></url>
• 删旧目录、清理旧 remote 和分支，再提交
• 关键点：subtree 的绑定靠的是 commit tree 路径和 upstream ref 的对应关系，路径一变，旧命令就彻底失联

真正容易被忽略的，是 subtree 的“单向绑定”本质：它把子仓库当成普通文件夹来管理，但底层 commit hash 仍隐式依赖上游。一旦上游强制 push（rebase/force-push），你本地的 pull 就可能产生重复文件或冲突，且无法自动修复——这种断裂不会报错，只会让下一次同步悄悄偏离预期。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！