先坦白讲我第一次想从 code.qt.io 上扒一个 Qt 示例的时候差点被这个网站逼疯。搜索引擎把我带到 code.qt.io 的 cgit 页面目录结构看得清清楚楚可翻来覆去就是找不到 Download 按钮换成 git clone又不知道该 clone 哪个仓库实在没办法去 clone qt5 超级模块结果 submodule 一拉就是几个 G网络稍微抖一下就前功尽弃。后来我才慢慢把“从 code.qt.io 下载单个示例项目/某个目录”这件事彻底摸透。这篇文章就把这个需求一次讲清楚先拆仓库结构再给官方场景下最好用的 git sparse-checkout 方案最后补上国内镜像、Qt 安装器、单文件直链这些备选通道以及我踩过的一堆坑。适合不想为了一两个 examples 目录拖回整个仓库、网络条件一般、或者只想快速参考官方示例源码的 Qt 开发者。1. 先弄清楚 code.qt.io 的仓库布局才能找到示例在哪1.1 示例代码和模块仓库的对应关系Qt 的源码并不是“一个仓库装下所有东西”而是按功能模块拆成了几十个独立仓库。这个设计直接影响你找示例的方式示例代码通常跟对应模块放在一起而不是集中在某个单独的“examples 总仓库”里。举个例子你想找基础窗口、按钮、布局这类 widgets 示例去 qtbase 仓库想找 QML 相关示例去 qtdeclarative 仓库想看 Modbus、CAN 总线这类串行总线示例去 qtserialbus 仓库。路径也基本有规律绝大多数模块仓库下面都有一个 examples 目录里面按功能再分子目录。模块仓库示例所在目录常见内容qtbaseexamples/widgets、examples/network、examples/sql基础控件、网络、数据库等qtdeclarativeexamples/qmlQML 界面、动画、状态机qtserialbusexamples/serialbusModbus、CAN 总线相关qtmultimediaexamples/multimedia音频、视频播放与采集这个规律非常重要。当你从 code.qt.io 下载单个目录时第一步永远不是“找下载按钮”而是先定位“这个示例到底在哪个仓库”。定位错了后面全是白折腾。1.2 为什么网页端没有“目录打包下载”这个按钮很多第一次用 code.qt.io 的朋友都会疑惑GitHub 上都有 Download ZIP这里怎么连个目录下载都没有原因在于 code.qt.io 的网页端是 cgit 代码浏览界面它的作用偏“查看”不是“分发”。cgit 虽然支持对仓库整体打快照snapshot也就是把整个仓库打包成 tar.xz 或 zip但它不支持“只打包某个子目录”。这种限制是 cgit 本身的设计决定的不是你看漏了按钮。既然网页端做不到目录级打包那就只能用 Git 客户端本身的目录级能力来曲线实现。Git 有一个专门干这件事的功能叫 sparse-checkout中文一般叫稀疏检出。它能让你在工作区里只保留仓库的某几个目录其他文件不落地。这个功能配合浅克隆、部分克隆一起用就能做到“只从 code.qt.io 拉取某一个示例目录”这正是本文的核心方案。2. 官方推荐姿势git sparse-checkout 只拉指定目录2.1 适合的 Git 版本与前置环境使用 sparse-checkout 前先确认一下 Git 版本。Git 2.25 及以上版本提供了完整的git sparse-checkout命令交互方式也更友好如果你还在用很老的 Git建议先升级否则就要手动改.git/info/sparse-checkout文件操作起来麻烦且容易出错。git --versionWindows 用户建议直接装 Git for WindowsmacOS 和 Linux 用户用系统自带或包管理器安装的最新版就行。整个下载过程不需要任何 GUI 工具只要你的机器能通过 HTTPS 访问 code.qt.io 就可以。2.2 完整命令与参数拆解以 qtserialbus 为例我用一个真实场景演示假设你的本地 Qt 是 5.15 系列现在想把 qtserialbus 模块下的examples/serialbus示例目录整个下载下来。打开终端依次执行git clone --depth 1 --branch 5.15 \ --filterblob:none --sparse \ https://code.qt.io/qt/qtserialbus.git cd qtserialbus git sparse-checkout set examples/serialbus执行完后当前目录下就只剩examples/serialbus这个目录里面是完整的示例源码别的文件一概没有。下面对命令里的参数逐个拆解理解它们你才知道遇到问题怎么调整--depth 1浅克隆只拉取最新一次提交不拉历史提交记录。历史对单纯看示例没有意义却能省掉大量网络传输。--branch 5.15指定分支或标签。这里写 5.15是因为它和本地 Qt 版本保持一致。如果删掉这个参数默认拉的是 dev 分支那上面可能是 Qt 6.x 或开发中版本接口很可能和你的 5.15 对不上。--filterblob:none部分克隆只下载提交对象和目录树对象不下载每个文件的真实内容。相当于你先看到仓库的“目录清单”等确定要哪些目录后再按需拉取对应文件内容。--sparse让克隆完成后工作区默认是空的配合后面的 sparse-checkout 使用。git sparse-checkout set examples/serialbus这一步告诉 Git工作区只保留examples/serialbus目录其他文件不检出。把整个过程想象成下载一个超大压缩包前先看压缩包里的文件清单确认后只解压你需要的那个文件夹其他压缩内容不落地。这就是 sparse-checkout 配合部分克隆能做到的事情。如果你执行git clone时报错提示服务器不支持filter比如remote error: filtering not supported说明 code.qt.io 在你当前网络环境或部署配置下没有开启部分克隆能力。这时候退而求其次把--filterblob:none去掉改用git clone --depth 1 --branch 5.15 --sparse https://code.qt.io/qt/qtserialbus.git cd qtserialbus git sparse-checkout set examples/serialbus命令一样能用区别是它会把当前提交里所有文件的对象都下载到本地但只检出指定目录。网络传输量仍然比全量克隆少得多只是没有blob:none那么极致。下载完成后可以用ls examples/serialbus看看结果。如果你不确定某个目录的完整路径进入仓库后先执行git ls-tree -d --name-only HEAD examples这会列出examples下有哪些目录然后再把git sparse-checkout set后面的路径换成目标路径即可。2.3 下载完成后如何增删目录sparse-checkout 最方便的一点是目录集合可以随时调整不需要重新下载仓库。想追加一个目录比如把examples/serialbus/modbus也加进来git sparse-checkout add examples/serialbus/modbus想改成只保留另外几个目录git sparse-checkout set examples/serialbus examples/canbus想查看当前工作区保留了哪些目录git sparse-checkout list这套操作在 CI 环境里特别有用。我经常在公司服务器上临时拉一个示例目录做参考用完直接整个文件夹删掉干净利落不用在本地留着一堆无用源码。3. 备用通道与加速方案镜像、安装器、单文件直链3.1 先检查本地 Qt 安装目录可能白白折腾了一整天在跑去 code.qt.io 下载任何东西之前先做一件事翻一下你本机 Qt 安装目录下的 Examples 文件夹。Windows 下默认位置一般是C:\Qt\5.15.2\ExamplesLinux 下通常是/opt/Qt/5.15.2/Examples。这里面的示例源码是安装 Qt 时随附带的。很多情况下你想要的示例早就躺在本地了根本不用联网下载。只有一种情况会缺失安装 Qt 时手动取消了 Examples 组件。如果你当初装的时候没勾选可以重新运行 Qt 的安装程序把 Examples 组件补装上这比任何 git 操作都省心。3.2 国内镜像与 GitHub 镜像如果在一些网络环境下访问 code.qt.io 特别慢或者git clone经常超时可以换两个思路第一个思路是换 GitHub 上的 Qt 官方镜像。Qt 在 GitHub 上维护了和 code.qt.io 对应的官方仓库比如github.com/qt/qtserialbus、github.com/qt/qtbase。命令完全一样只是把 URL 换掉git clone --depth 1 --branch 5.15 \ --filterblob:none --sparse \ https://github.com/qt/qtserialbus.git cd qtserialbus git sparse-checkout set examples/serialbusGitHub 对部分克隆和稀疏检出的支持通常更稳定很多网络环境访问 GitHub 也比访问 code.qt.io 更顺畅。第二个思路是使用国内镜像站下载 Qt 的源码包或安装包比如清华 TUNA 和中科大 USTC 都提供 Qt 的发布镜像清华https://mirrors.tuna.tsinghua.edu.cn/qt/中科大https://mirrors.ustc.edu.cn/qtproject/需要说明的是镜像站主要镜像的是“发布包”也就是整包的安装程序或源码压缩包并不是让你像 git 仓库一样按目录拉取。如果你只是为了网上某个目录级示例镜像站帮不上忙但如果你需要完整离线源码包镜像站下载速度会快很多。3.3 只需要单个源文件时的 cgit plain 直链如果需求更小只是想看某个.cpp或.h文件的内容根本不用下载整个仓库连 sparse-checkout 都用不上。code.qt.io 的 cgit 界面提供 plain 模式可以直接拿到某个文件的纯文本内容。比如想获取 qtbase 仓库 5.15 分支下examples/widgets/mainwindow/mainwindow.cpp这个文件curl -O https://code.qt.io/cgit/qt/qtbase.git/plain/examples/widgets/mainwindow/mainwindow.cpp?h5.15浏览器直接打开这个 URL看到的也是纯源码而不是 HTML 页面。?h5.15是 cgit 用来指定分支或标签的参数不写默认取当前默认分支。这个方法只适合单个文件。有人可能想用wget -r递归抓整个目录我劝你放弃因为 cgit 的 plain 模式是逐个文件访问的递归抓下来会混入大量页面框架整理成本比下载仓库还高。3.4 按场景选方案的速查表你的场景推荐手段备注本机已经装了 Qt直接翻 Examples 目录最快无需联网只要一个源文件cgit plain 直链一行 curl 搞定要一整个示例目录git sparse-checkout 从 code.qt.io 或 GitHub 镜像拉推荐精准省流量需要完整离线源码包镜像站下载源码压缩包体积大适合整包分发要看 dev 分支最新示例sparse-checkout 且不指定 --branch代码可能不兼容稳定版这张表基本覆盖了我日常遇到的所有情况。你按这个逻辑选至少不会在错误的方向上浪费时间。4. 踩坑实录与排查速查表4.1 六个高频问题及处理办法实际操作中问题通常集中在下面几个点上。我按出现频率排个序问题现象原因与处理办法clone 速度慢或反复超时网络环境问题。用--depth 1 --single-branch减少传输量或者干脆换 GitHub 镜像仓库提示filtering not supported服务器或网络部署不支持部分克隆。去掉--filterblob:none用--depth 1 --sparse降级方案sparse-checkout set 后目录是空的路径写错了。先运行git ls-tree -d --name-only HEAD examples确认正确的目录名再重新 set下载的代码和本地 Qt 版本 API 对不上没指定--branch拉到了 dev 分支。确认你的 Qt 版本后用--branch 版本号重新拉取示例编译运行时报qt_qpa_platform_plugin_path错误Qt 平台的 platform 插件没有找到。常见的场景是把示例拷出 Qt 安装目录后自己编译运行导致运行时找不到插件路径磁盘占用没有想象中小服务器不支持部分克隆时--depth 1 --sparse仍会下载当前提交的全部文件对象如果对流量特别敏感优先从 GitHub 镜像试blob:none关于qt_qpa_platform_plugin_path这个报错我多说一句。它通常发生在 Windows 上比如你装了 Qt 5.15.2 到D:\Qt\5.15.2\msvc2019_64拿 sparse-checkout 拉下来的示例源码放到另外的目录用 CMake 或 qmake 编译运行时 Qt 找不到platforms/qwindows.dll。最简单的解决办法是把示例放在 Qt 安装目录的相近层级下用 Qt 自带的“Qt 5.15.2 (MSVC 2019 64-bit)”命令行环境来 qmake/make如果已经编译出可执行文件而要发布给别人就用windeployqt把依赖的插件和运行库一起拷过去。这不是 sparse-checkout 的问题而是任何脱离 Qt 安装目录构建的示例都会遇到的运行时环境问题。关于 clone 慢的问题也可以在命令层面优化。比如指定单分支并限制深度git clone --depth 1 --single-branch --branch 5.15 \ --filterblob:none --sparse \ https://code.qt.io/qt/qtserialbus.git--single-branch让 Git 只拉取指定分支的引用信息不会拉其他分支的引用速度会有明显提升。4.2 一个适合大多数人的工作流最后分享一个我平时一直在用的工作流按优先级从高到低第一本机有没有装对应版本的 Qt有就先看 Examples没有就继续下一步。第二只需要单个源文件直接用 cgit plain 直链一条 curl 搞定。第三需要整个示例目录用git clone --depth 1 --branch 版本号 --filterblob:none --sparse加git sparse-checkout set仓库优先选 code.qt.io慢了或超时换 GitHub 镜像。第四如果目标机器上已经有 Git 环境但没装 Qt你也可以在拉完目录后直接阅读源码参考不一定要能编译通过。很多官方示例的代码逻辑是自解释的纯阅读也有很大价值。我把常用的几个仓库和目录记成了一个简单的 shell 函数比如输入qtget qtserialbus examples/serialbus 5.15就能一键拉取目标目录。这样几次用下来基本告别了在网页上一层层点目录的原始操作。我个人在实际操作中的体会是越是不起眼的目录级下载需求越容易让人踩进“整仓克隆”的坑。你原本只想看一个 Modbus 示例结果拖回来好几个 G 的源码网络一差心态直接崩。换 sparse-checkout 之后十几秒就能把目标目录拉到本地这才是面对这种需求该有的效率。如果你也经常被各种 Qt 示例折腾先把这套命令存下来下次直接从 code.qt.io 精准下载目录能省下大把时间。 
长河君 · 2026/9/11 12:03:04 · 阅读 1.2k git sparse-checkout实战：从code.qt.io下载单个Qt示例目录
先坦白讲我第一次想从 code.qt.io 上扒一个 Qt 示例的时候差点被这个网站逼疯。搜索引擎把我带到 code.qt.io 的 cgit 页面目录结构看得清清楚楚可翻来覆去就是找不到 Download 按钮换成 git clone又不知道该 clone 哪个仓库实在没办法去 clone qt5 超级模块结果 submodule 一拉就是几个 G网络稍微抖一下就前功尽弃。后来我才慢慢把“从 code.qt.io 下载单个示例项目/某个目录”这件事彻底摸透。这篇文章就把这个需求一次讲清楚先拆仓库结构再给官方场景下最好用的 git sparse-checkout 方案最后补上国内镜像、Qt 安装器、单文件直链这些备选通道以及我踩过的一堆坑。适合不想为了一两个 examples 目录拖回整个仓库、网络条件一般、或者只想快速参考官方示例源码的 Qt 开发者。1. 先弄清楚 code.qt.io 的仓库布局才能找到示例在哪1.1 示例代码和模块仓库的对应关系Qt 的源码并不是“一个仓库装下所有东西”而是按功能模块拆成了几十个独立仓库。这个设计直接影响你找示例的方式示例代码通常跟对应模块放在一起而不是集中在某个单独的“examples 总仓库”里。举个例子你想找基础窗口、按钮、布局这类 widgets 示例去 qtbase 仓库想找 QML 相关示例去 qtdeclarative 仓库想看 Modbus、CAN 总线这类串行总线示例去 qtserialbus 仓库。路径也基本有规律绝大多数模块仓库下面都有一个 examples 目录里面按功能再分子目录。模块仓库示例所在目录常见内容qtbaseexamples/widgets、examples/network、examples/sql基础控件、网络、数据库等qtdeclarativeexamples/qmlQML 界面、动画、状态机qtserialbusexamples/serialbusModbus、CAN 总线相关qtmultimediaexamples/multimedia音频、视频播放与采集这个规律非常重要。当你从 code.qt.io 下载单个目录时第一步永远不是“找下载按钮”而是先定位“这个示例到底在哪个仓库”。定位错了后面全是白折腾。1.2 为什么网页端没有“目录打包下载”这个按钮很多第一次用 code.qt.io 的朋友都会疑惑GitHub 上都有 Download ZIP这里怎么连个目录下载都没有原因在于 code.qt.io 的网页端是 cgit 代码浏览界面它的作用偏“查看”不是“分发”。cgit 虽然支持对仓库整体打快照snapshot也就是把整个仓库打包成 tar.xz 或 zip但它不支持“只打包某个子目录”。这种限制是 cgit 本身的设计决定的不是你看漏了按钮。既然网页端做不到目录级打包那就只能用 Git 客户端本身的目录级能力来曲线实现。Git 有一个专门干这件事的功能叫 sparse-checkout中文一般叫稀疏检出。它能让你在工作区里只保留仓库的某几个目录其他文件不落地。这个功能配合浅克隆、部分克隆一起用就能做到“只从 code.qt.io 拉取某一个示例目录”这正是本文的核心方案。2. 官方推荐姿势git sparse-checkout 只拉指定目录2.1 适合的 Git 版本与前置环境使用 sparse-checkout 前先确认一下 Git 版本。Git 2.25 及以上版本提供了完整的git sparse-checkout命令交互方式也更友好如果你还在用很老的 Git建议先升级否则就要手动改.git/info/sparse-checkout文件操作起来麻烦且容易出错。git --versionWindows 用户建议直接装 Git for WindowsmacOS 和 Linux 用户用系统自带或包管理器安装的最新版就行。整个下载过程不需要任何 GUI 工具只要你的机器能通过 HTTPS 访问 code.qt.io 就可以。2.2 完整命令与参数拆解以 qtserialbus 为例我用一个真实场景演示假设你的本地 Qt 是 5.15 系列现在想把 qtserialbus 模块下的examples/serialbus示例目录整个下载下来。打开终端依次执行git clone --depth 1 --branch 5.15 \ --filterblob:none --sparse \ https://code.qt.io/qt/qtserialbus.git cd qtserialbus git sparse-checkout set examples/serialbus执行完后当前目录下就只剩examples/serialbus这个目录里面是完整的示例源码别的文件一概没有。下面对命令里的参数逐个拆解理解它们你才知道遇到问题怎么调整--depth 1浅克隆只拉取最新一次提交不拉历史提交记录。历史对单纯看示例没有意义却能省掉大量网络传输。--branch 5.15指定分支或标签。这里写 5.15是因为它和本地 Qt 版本保持一致。如果删掉这个参数默认拉的是 dev 分支那上面可能是 Qt 6.x 或开发中版本接口很可能和你的 5.15 对不上。--filterblob:none部分克隆只下载提交对象和目录树对象不下载每个文件的真实内容。相当于你先看到仓库的“目录清单”等确定要哪些目录后再按需拉取对应文件内容。--sparse让克隆完成后工作区默认是空的配合后面的 sparse-checkout 使用。git sparse-checkout set examples/serialbus这一步告诉 Git工作区只保留examples/serialbus目录其他文件不检出。把整个过程想象成下载一个超大压缩包前先看压缩包里的文件清单确认后只解压你需要的那个文件夹其他压缩内容不落地。这就是 sparse-checkout 配合部分克隆能做到的事情。如果你执行git clone时报错提示服务器不支持filter比如remote error: filtering not supported说明 code.qt.io 在你当前网络环境或部署配置下没有开启部分克隆能力。这时候退而求其次把--filterblob:none去掉改用git clone --depth 1 --branch 5.15 --sparse https://code.qt.io/qt/qtserialbus.git cd qtserialbus git sparse-checkout set examples/serialbus命令一样能用区别是它会把当前提交里所有文件的对象都下载到本地但只检出指定目录。网络传输量仍然比全量克隆少得多只是没有blob:none那么极致。下载完成后可以用ls examples/serialbus看看结果。如果你不确定某个目录的完整路径进入仓库后先执行git ls-tree -d --name-only HEAD examples这会列出examples下有哪些目录然后再把git sparse-checkout set后面的路径换成目标路径即可。2.3 下载完成后如何增删目录sparse-checkout 最方便的一点是目录集合可以随时调整不需要重新下载仓库。想追加一个目录比如把examples/serialbus/modbus也加进来git sparse-checkout add examples/serialbus/modbus想改成只保留另外几个目录git sparse-checkout set examples/serialbus examples/canbus想查看当前工作区保留了哪些目录git sparse-checkout list这套操作在 CI 环境里特别有用。我经常在公司服务器上临时拉一个示例目录做参考用完直接整个文件夹删掉干净利落不用在本地留着一堆无用源码。3. 备用通道与加速方案镜像、安装器、单文件直链3.1 先检查本地 Qt 安装目录可能白白折腾了一整天在跑去 code.qt.io 下载任何东西之前先做一件事翻一下你本机 Qt 安装目录下的 Examples 文件夹。Windows 下默认位置一般是C:\Qt\5.15.2\ExamplesLinux 下通常是/opt/Qt/5.15.2/Examples。这里面的示例源码是安装 Qt 时随附带的。很多情况下你想要的示例早就躺在本地了根本不用联网下载。只有一种情况会缺失安装 Qt 时手动取消了 Examples 组件。如果你当初装的时候没勾选可以重新运行 Qt 的安装程序把 Examples 组件补装上这比任何 git 操作都省心。3.2 国内镜像与 GitHub 镜像如果在一些网络环境下访问 code.qt.io 特别慢或者git clone经常超时可以换两个思路第一个思路是换 GitHub 上的 Qt 官方镜像。Qt 在 GitHub 上维护了和 code.qt.io 对应的官方仓库比如github.com/qt/qtserialbus、github.com/qt/qtbase。命令完全一样只是把 URL 换掉git clone --depth 1 --branch 5.15 \ --filterblob:none --sparse \ https://github.com/qt/qtserialbus.git cd qtserialbus git sparse-checkout set examples/serialbusGitHub 对部分克隆和稀疏检出的支持通常更稳定很多网络环境访问 GitHub 也比访问 code.qt.io 更顺畅。第二个思路是使用国内镜像站下载 Qt 的源码包或安装包比如清华 TUNA 和中科大 USTC 都提供 Qt 的发布镜像清华https://mirrors.tuna.tsinghua.edu.cn/qt/中科大https://mirrors.ustc.edu.cn/qtproject/需要说明的是镜像站主要镜像的是“发布包”也就是整包的安装程序或源码压缩包并不是让你像 git 仓库一样按目录拉取。如果你只是为了网上某个目录级示例镜像站帮不上忙但如果你需要完整离线源码包镜像站下载速度会快很多。3.3 只需要单个源文件时的 cgit plain 直链如果需求更小只是想看某个.cpp或.h文件的内容根本不用下载整个仓库连 sparse-checkout 都用不上。code.qt.io 的 cgit 界面提供 plain 模式可以直接拿到某个文件的纯文本内容。比如想获取 qtbase 仓库 5.15 分支下examples/widgets/mainwindow/mainwindow.cpp这个文件curl -O https://code.qt.io/cgit/qt/qtbase.git/plain/examples/widgets/mainwindow/mainwindow.cpp?h5.15浏览器直接打开这个 URL看到的也是纯源码而不是 HTML 页面。?h5.15是 cgit 用来指定分支或标签的参数不写默认取当前默认分支。这个方法只适合单个文件。有人可能想用wget -r递归抓整个目录我劝你放弃因为 cgit 的 plain 模式是逐个文件访问的递归抓下来会混入大量页面框架整理成本比下载仓库还高。3.4 按场景选方案的速查表你的场景推荐手段备注本机已经装了 Qt直接翻 Examples 目录最快无需联网只要一个源文件cgit plain 直链一行 curl 搞定要一整个示例目录git sparse-checkout 从 code.qt.io 或 GitHub 镜像拉推荐精准省流量需要完整离线源码包镜像站下载源码压缩包体积大适合整包分发要看 dev 分支最新示例sparse-checkout 且不指定 --branch代码可能不兼容稳定版这张表基本覆盖了我日常遇到的所有情况。你按这个逻辑选至少不会在错误的方向上浪费时间。4. 踩坑实录与排查速查表4.1 六个高频问题及处理办法实际操作中问题通常集中在下面几个点上。我按出现频率排个序问题现象原因与处理办法clone 速度慢或反复超时网络环境问题。用--depth 1 --single-branch减少传输量或者干脆换 GitHub 镜像仓库提示filtering not supported服务器或网络部署不支持部分克隆。去掉--filterblob:none用--depth 1 --sparse降级方案sparse-checkout set 后目录是空的路径写错了。先运行git ls-tree -d --name-only HEAD examples确认正确的目录名再重新 set下载的代码和本地 Qt 版本 API 对不上没指定--branch拉到了 dev 分支。确认你的 Qt 版本后用--branch 版本号重新拉取示例编译运行时报qt_qpa_platform_plugin_path错误Qt 平台的 platform 插件没有找到。常见的场景是把示例拷出 Qt 安装目录后自己编译运行导致运行时找不到插件路径磁盘占用没有想象中小服务器不支持部分克隆时--depth 1 --sparse仍会下载当前提交的全部文件对象如果对流量特别敏感优先从 GitHub 镜像试blob:none关于qt_qpa_platform_plugin_path这个报错我多说一句。它通常发生在 Windows 上比如你装了 Qt 5.15.2 到D:\Qt\5.15.2\msvc2019_64拿 sparse-checkout 拉下来的示例源码放到另外的目录用 CMake 或 qmake 编译运行时 Qt 找不到platforms/qwindows.dll。最简单的解决办法是把示例放在 Qt 安装目录的相近层级下用 Qt 自带的“Qt 5.15.2 (MSVC 2019 64-bit)”命令行环境来 qmake/make如果已经编译出可执行文件而要发布给别人就用windeployqt把依赖的插件和运行库一起拷过去。这不是 sparse-checkout 的问题而是任何脱离 Qt 安装目录构建的示例都会遇到的运行时环境问题。关于 clone 慢的问题也可以在命令层面优化。比如指定单分支并限制深度git clone --depth 1 --single-branch --branch 5.15 \ --filterblob:none --sparse \ https://code.qt.io/qt/qtserialbus.git--single-branch让 Git 只拉取指定分支的引用信息不会拉其他分支的引用速度会有明显提升。4.2 一个适合大多数人的工作流最后分享一个我平时一直在用的工作流按优先级从高到低第一本机有没有装对应版本的 Qt有就先看 Examples没有就继续下一步。第二只需要单个源文件直接用 cgit plain 直链一条 curl 搞定。第三需要整个示例目录用git clone --depth 1 --branch 版本号 --filterblob:none --sparse加git sparse-checkout set仓库优先选 code.qt.io慢了或超时换 GitHub 镜像。第四如果目标机器上已经有 Git 环境但没装 Qt你也可以在拉完目录后直接阅读源码参考不一定要能编译通过。很多官方示例的代码逻辑是自解释的纯阅读也有很大价值。我把常用的几个仓库和目录记成了一个简单的 shell 函数比如输入qtget qtserialbus examples/serialbus 5.15就能一键拉取目标目录。这样几次用下来基本告别了在网页上一层层点目录的原始操作。我个人在实际操作中的体会是越是不起眼的目录级下载需求越容易让人踩进“整仓克隆”的坑。你原本只想看一个 Modbus 示例结果拖回来好几个 G 的源码网络一差心态直接崩。换 sparse-checkout 之后十几秒就能把目标目录拉到本地这才是面对这种需求该有的效率。如果你也经常被各种 Qt 示例折腾先把这套命令存下来下次直接从 code.qt.io 精准下载目录能省下大把时间。