1. PlatformIO 工程为什么越编译越大:从 27MB 到 300KB 的清理思路
做嵌入式的人对代码开发工具的体积膨胀大多有体会:PlatformIO 工程刚建时很干净,编译几次之后,.pio 目录就能从几 MB 涨到几十 MB,换台机器拷贝或归档时尤其难受。我手头一个测试工程在 Windows 11 + PlatformIO IDE(VS Code 扩展)下占到 27MB,跑完一轮清理脚本后只剩 300KB。差别不在源码,而在编译中间产物、依赖缓存和调试文件。这篇就把这套 PlatformIO 工程瘦身脚本拆开讲清楚:哪些目录可以直接删,哪些文件删了要付重新下载或补全失效的代价,脚本在 Linux/macOS 与 Windows 下怎么写,以及清理时最容易翻车的几个点。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具 PlatformIO 的目录解剖:哪些能删、哪些删了要付代价
PlatformIO 把编译过程产生的所有东西都收在工程根目录的 .pio 下,源码目录通常只有 src、include、lib 和 platformio.ini。这意味着清理时最该盯住的是 .pio,而不是整个工程乱扫。但 .pio 里面也不是铁板一块,有的目录删了只是触发一次全量编译,有的目录删了会让下一次编译重新下载依赖,还有的文件删了会影响 VS Code 的代码补全和调试配置。先把这张表看清楚,再动手写脚本,能少走很多弯路。
| 路径 | 作用 | 删除后的代价 |
|---|---|---|
.pio/build |
编译生成的目标文件、链接文件等中间产物,通常是体积最大的部分 | 下次编译全量重来,耗时增加,但源码不受影响 |
.pio/deps |
编译工具链的依赖缓存,用来加速后续编译 | 下次编译重新准备依赖,可能触发额外下载 |
.pio/.cache |
PlatformIO 的内部运行时缓存 | 影响较小,后续运行会重新生成 |
.pio/libdeps |
第三方依赖库文件 | 下次编译会自动重新下载,网络不佳时很耗时 |
compile_commands.json |
Clangd 等语言服务器使用的编译数据库 | 下次编译会重新生成,但清理后立刻打开工程补全会变差 |
c_cpp_properties.json |
VS Code C/C++ 插件的配置 | 删除后可能恢复默认,头文件路径和补全配置需要重新弄 |
*.elf / *.bin / *.hex |
可执行文件、烧录固件、另一种固件格式 | 需要重新编译才能得到 |
*.map / *.lst |
内存映射文件、汇编列表文件 | 分析内存占用和汇编对应关系时没有依据 |
*.log / *.tra / JLinkLog.txt |
编译日志、跟踪文件、调试器日志 | 排查历史问题时缺少现场记录 |
2.1 .pio/build 与 .pio/deps 的职责边界
.pio/build 是脚本里最该优先清理的目录。它存放的是编译过程中生成的目标文件、链接文件和其他中间产物,每次改代码重新编译时,PlatformIO 会按需更新这些文件,所以它的体积会随着编译次数增加而膨胀。删掉 .pio/build 不会动源码,也不会动 platformio.ini,代价只是下一次编译从零开始。对归档、拷贝、提交前清理来说,这个代价完全可以接受。反过来说,如果你正在频繁编译调试,每改一行就删一次 build,那是给自己找麻烦,编译时间会明显变长。
.pio/deps 的定位稍微不同。它不是最终固件,也不是业务源码,而是编译工具链的依赖缓存,作用是加速后续编译。删掉它之后,PlatformIO 下一次编译会重新准备这些依赖,多数情况下能自动完成,但在网络不稳定或者工具链版本特殊的环境里,可能会卡在依赖准备阶段。所以我的习惯是:日常编译不动 .pio/deps,只在工程归档、换机拷贝或者确定要清干净时删。脚本里把 .pio/build、.pio/deps、.pio/.cache 三条放在最前面,就是因为它们都是“删了能重新生成”的目录,但重新生成的代价不一样,顺序上先删体积最大的 build,再删 deps 和 .cache,清理过程更直观。
.pio/.cache 是 PlatformIO 的内部缓存目录,存放一些运行时缓存数据。它通常不是体积大头,删了之后 PlatformIO 后续运行会重新建立。这个目录可以删,但不要指望删了它能带来肉眼可见的瘦身效果。真正占空间的是 build 和 libdeps,.cache 更多是顺手清理。
2.2 中间产物的分布:elf/bin/hex/map/lst/tmp
目录清完之后,工程里还会散落不少文件。*.elf 是 Executable and Linkable Format 文件,包含调试信息;*.bin 是最终烧录到设备的二进制固件;*.hex 是另一种常见的固件格式,Intel HEX;*.map 是内存映射文件,详细列出代码段、数据段等内存占用情况;*.lst 是汇编列表文件,包含源码和对应的机器码;*.tmp 是各种临时文件。这些文件通常分布在 .pio/build 下面,但也可能被手动复制到工程根目录、release 目录或者文档目录里。
这就是脚本里 find . -name '*.elf' -delete 这类写法的风险所在:find . 是从当前目录开始递归整个工程,不是只扫 .pio。如果工程里有一个 docs 目录,里面放着历史版本的 *.bin 或 *.map 用作说明,脚本会一并删掉。清理前先用 find . -name '*.map' -print 看一眼命中列表,比事后找后悔药有用得多。
*.log、*.tra、JLinkLog.txt 属于日志和跟踪文件。它们不影响编译,也不影响烧录,但排查历史问题时可能是唯一现场。脚本默认删除这些文件,适合归档前清理;如果当前正在查一个偶发问题,先把日志复制出去再跑清理。
2.3 libdeps 与 compile_commands.json 的保留取舍
.pio/libdeps 是第三方依赖库文件存放处。脚本里默认把 rm -rf .pio/libdeps 注释掉了,这个处理很关键:删掉 libdeps 后,PlatformIO 下次编译会自动重新下载这些依赖。对于频繁清理且网络不佳的环境,保留 libdeps 能省掉大量等待时间;如果确实要归档一个干净工程,再把这行注释打开。判断标准很简单:这次清理是为了“省空间”还是为了“打包给别人”。省空间可以保留 libdeps,打包给别人可以删,但要在说明里写清楚首次编译需要联网准备依赖。
compile_commands.json 是 Clangd 等语言服务器使用的编译数据库,删了之后下一次编译会重新生成。问题在于“下一次编译”之前,VS Code 里的代码补全、跳转、头文件解析可能会明显变差。很多人清理完工程,打开编辑器发现满屏红波浪线,以为工程坏了,其实只是编译数据库被删了。我的做法是:日常清理保留这个文件,只在归档副本里删。
c_cpp_properties.json 是 VS Code C/C++ 插件的配置,通常应该保留,除非你希望恢复默认。脚本里默认删除这一行,风险比删 compile_commands.json 还大,因为重新编译不一定立刻把它恢复成你原来的配置。更稳妥的写法是把这一行注释掉,或者只在一个专门用于打包的脚本副本里保留删除动作。*.gdb 是 GDB 调试器相关文件,删了会影响调试配置,清理前也要想清楚当前是否还在调试。
3. 用代码开发工具写瘦身脚本:从 rm -rf 到 find 删除
把上面的取舍落成一个可执行脚本,结构并不复杂:先删三个缓存目录,再按扩展名删中间产物,最后删日志和 IDE 辅助文件。关键是每一段都要知道自己在删什么,而不是把一堆 rm -rf 堆在一起。下面这版脚本来自实际使用的清理逻辑,保留了 libdeps 不删的默认行为,适合日常归档前跑一遍。
bash复制#!/bin/bash
# 清理 PlatformIO 编译文件和目录
# .pio/build: 编译中间产物,体积最大的部分
rm -rf .pio/build
# .pio/deps: 编译工具链依赖缓存
rm -rf .pio/deps
# .pio/.cache: PlatformIO 内部运行时缓存
rm -rf .pio/.cache
# 保留第三方依赖库文件;需要彻底清理时再打开下面这行
# rm -rf .pio/libdeps
# 删除固件和中间文件
find . -name '*.elf' -delete
find . -name '*.bin' -delete
find . -name '*.hex' -delete
find . -name '*.map' -delete
find . -name '*.lst' -delete
find . -name '*.tmp' -delete
# 删除日志和缓存文件
find . -name '*.log' -delete
find . -name '*.tra' -delete
find . -name 'JLinkLog.txt' -delete
# 删除编译数据库和 IDE 相关文件
# c_cpp_properties.json 建议保留,删除前确认不需要原有补全配置
find . -name 'compile_commands.json' -delete
find . -name '*.gdb' -delete
# find . -name 'c_cpp_properties.json' -delete
echo "清理完成,保留关键配置文件及源码"
这段脚本没有加 set -e,因为 find 在没有匹配文件时也会正常退出,不需要因为某一条没命中就中断整个清理。真正需要防的是路径写错和在错误目录执行,这两个问题靠执行前的确认步骤解决,不靠脚本自己猜。
3.1 目录级清理:三条 rm -rf 的顺序与含义
rm -rf .pio/build 里的 -r 表示递归删除目录及其内容,-f 表示强制删除、不弹确认。两个参数合在一起,删除时不会给你二次确认的机会,所以路径必须是相对工程根目录的 .pio/build。如果当前 shell 不在工程根目录,这条命令要么找不到目录,要么删到别的工程的 .pio/build。执行前先做两步确认:
bash复制pwd
ls -la .pio
pwd 打印当前工作目录,确认它下面有 platformio.ini;ls -la .pio 看 .pio 是否存在,以及 build、deps、.cache 这几个子目录的实际名字。Windows 下目录名大小写不敏感,Linux/macOS 下大小写敏感,.pio 不要写成 .Pio。
.pio/deps 删除后,下一次编译会重新准备工具链依赖。这个目录的体积不一定最大,但在网络受限的环境里,重新准备的代价可能比编译本身还高。所以它适合在“确定要归档”时删,不适合每改一次代码就删。.pio/.cache 删除后影响最小,PlatformIO 后续运行会重建,放在第三条是顺手清理,不是瘦身主力。
3.2 文件级清理:find 匹配与 -delete 的安全边界
find . -name '*.elf' -delete 拆开看:. 表示从当前目录开始递归;-name '*.elf' 按文件名匹配,通配符由 find 自己解释,不需要 shell 展开;-delete 表示对匹配到的文件执行删除。它不会删除目录,只会删除文件,但递归范围是整个当前目录,所以工程里任何位置的 *.elf 都会命中。
安全做法是先 -print 预览:
bash复制find . -name '*.elf' -print
find . -name '*.map' -print
find . -name '*.bin' -print
确认输出里没有你想保留的历史固件或文档附件,再把 -print 换成 -delete。*.map 和 *.bin 是最容易误伤的两类:前者可能被复制到文档目录用来说明内存布局,后者可能被放在 release 目录作为历史版本。如果只想清理 .pio 内部,可以把 find . 收窄成 find .pio,例如:
bash复制find .pio -name '*.map' -delete
代价是工程根目录下散落的固件不会被清掉,需要按自己的目录习惯决定。JLinkLog.txt 是固定文件名,匹配时注意大小写;*.tra 是某些工具链可能生成的跟踪文件,不是每个工程都有,删不到也不会报错。
3.3 Windows 下的等价写法:bat 脚本与 VS Code Task
Windows 下可以把同样的逻辑保存成 .bat 文件,放在工程根目录执行。rmdir /s /q 对应递归强制删除目录,del /s /q 对应递归强制删除文件:
bat复制@echo off
rmdir /s /q .pio\build
rmdir /s /q .pio\deps
rmdir /s /q .pio\.cache
rem 需要保留第三方依赖时不要删除 libdeps
rem rmdir /s /q .pio\libdeps
del /s /q *.elf
del /s /q *.bin
del /s /q *.hex
del /s /q *.map
del /s /q *.lst
del /s /q *.tmp
del /s /q *.log
del /s /q *.tra
del /s /q JLinkLog.txt
del /s /q compile_commands.json
del /s /q *.gdb
rem c_cpp_properties.json 建议保留
rem del /s /q c_cpp_properties.json
echo 清理完成,保留关键配置文件及源码
del /s /q *.elf 会从当前目录递归删除所有匹配文件,和 bash 版的 find . 一样有误伤风险。执行前把 .bat 放在工程根目录,不要放在 src 或 docs 子目录里双击。更稳妥的方式是通过 VS Code 任务执行,把工作目录固定到工程根目录:
json复制{
"version": "2.0.0",
"tasks": [
{
"label": "PlatformIO 工程瘦身",
"type": "shell",
"command": "bash",
"args": ["./platformiokill.sh"],
"options": {
"cwd": "${workspaceFolder}"
},
"problemMatcher": []
}
]
}
cwd 指定为 ${workspaceFolder},任务运行时一定在工程根目录,不会因为当前打开的是子目录而清错地方。Windows 下把 command 改成 cmd,args 改成 ["/c", "platformiokill.bat"] 即可。材料里提到可以把清理脚本和 VS Code 任务结合,甚至绑定快捷键实现“一键编译 + 清理”,但我不建议在每次编译后自动删 build,那样会把增量编译的优势丢掉,只在归档或交接前手动触发更合理。
4. 代码开发工具清理的避坑与排查:现象、原因、解决
清理脚本本身不长,翻车点却不少。下面这几条都是围绕脚本里的相对路径、递归删除和保留项来的,每条按现象、原因、解决写清楚,照着排查能少走弯路。
4.1 删完 libdeps 后首次编译卡在下载依赖
现象:清理完成后第一次编译,进度长时间停在准备依赖或下载库的阶段,终端没有明显报错,但编译迟迟不结束。
原因:.pio/libdeps 存放第三方依赖库文件,脚本里一旦打开 rm -rf .pio/libdeps,PlatformIO 下次编译就会自动重新下载这些依赖。网络不佳时,这一步会非常慢,甚至反复重试。
解决:日常清理保持 libdeps 那行注释状态,不删第三方库;只有归档或打包给别人时才删,并在交接说明里写清楚首次编译需要联网。如果已经删了,恢复网络后重新编译一次,让 PlatformIO 把依赖重新拉下来,不要在半途反复中断。
4.2 删掉 c_cpp_properties.json 后补全和跳转变差
现象:清理后打开 VS Code,头文件路径出现波浪线,函数跳转变慢或失效,C/C++ 插件的配置看起来像被重置了。
原因:c_cpp_properties.json 是 VS Code C/C++ 插件的配置,脚本默认删除这一行时,原有补全配置可能丢失。它和 compile_commands.json 不同,后者下次编译会重新生成,前者不一定立刻恢复成你原来的设置。
解决:把脚本里删除 c_cpp_properties.json 的那行注释掉,日常保留这个文件;如果已经删了,重新配置头文件搜索路径,或者从版本控制里恢复。compile_commands.json 删了之后也要重新编译一次再打开编辑器,否则 Clangd 这类语言服务器没有编译数据库可用。
4.3 在子目录执行脚本,提示清理完成但工程没瘦
现象:脚本输出“清理完成”,但回到工程根目录一看,.pio 的体积几乎没变。
原因:脚本里的 .pio/build、.pio/deps 都是相对路径,find . 也从当前目录开始。如果在 src 或 docs 子目录里执行,删除的是子目录下不存在的路径,或者只删到子目录里的零散文件,工程根目录的 .pio 根本没被碰到。
解决:执行前先 cd 到包含 platformio.ini 的工程根目录,用 pwd 确认,再跑脚本。用 VS Code 任务时把 cwd 固定为 ${workspaceFolder},不要依赖当前打开的编辑器目录。这个坑很常见,尤其是把脚本复制到别处双击运行的时候。
4.4 find 删掉源码目录里的同名 .map 或 .bin
现象:清理后,文档目录里用来讲解内存布局的 *.map 不见了,或者 release 目录下准备留档的 *.bin 被删了。
原因:find . -name '*.map' -delete 从工程根目录递归整个工程,不区分 .pio/build 和 docs。只要文件名匹配,无论在哪个子目录都会被删。
解决:清理前先用 find . -name '*.map' -print 预览命中列表,确认没有要保留的文件;或者把递归范围收窄到 .pio,写成 find .pio -name '*.map' -delete。如果历史固件必须保留,把它们移到工程外的归档目录,不要放在会被脚本扫到的路径下。
4.5 清理后想分析内存占用,map 文件没了
现象:需要看代码段、数据段占用了多少 Flash 和 RAM 时,发现 *.map 已经被清理掉,只能重新编译。
原因:*.map 是内存映射文件,详细列出代码段、数据段等内存占用情况。脚本默认删除所有 *.map,清理时很痛快,分析时就没有依据了。
解决:归档前先把最新一次的 *.map 复制到 docs 或 release 目录单独保存,再跑清理;或者把脚本里删除 *.map 的那行注释掉,保留最近一次编译的内存映射。*.lst 也是同理,汇编列表在排查启动代码和优化问题时有用,是否删除要看当前阶段。
5. 把瘦身接进日常:体积验证与 VS Code 任务绑定
清理完不能只看脚本输出,要看实际体积。Linux/macOS 下可以用 du -sh 对比清理前后的 .pio 和整个工程:
bash复制du -sh .pio
du -sh .
Windows PowerShell 下可以统计 .pio 的总字节数:
powershell复制Get-ChildItem .pio -Recurse | Measure-Object -Property Length -Sum
du -sh 的 -s 表示汇总,-h 表示人类可读单位;PowerShell 的 Measure-Object -Property Length -Sum 会把递归列出的文件长度累加。清理前后各跑一次,数字对不上就回去看是不是在错误目录执行,或者 libdeps 被误删后又被重新下载。
| 项目 | 清理前占用 | 清理后占用 |
|---|---|---|
| 测试工程 | 27MB | 300KB |
上面这组数字来自 Windows 11 + PlatformIO IDE(VS Code 扩展)下的实际测试,工程不同、依赖多少不同,绝对值会有差异,但数量级变化能说明问题。我的习惯是:归档前先 pwd 确认在工程根目录,跑一遍脚本,再用 du -sh .pio 看体积;如果这次要分析内存,先把 *.map 复制出去再清理。VS Code 任务只用来手动触发,不挂到每次编译后,避免把增量编译的缓存反复删掉。从那以后我每次打包前都强制走一遍“确认目录、预览命中文件、执行清理、核对体积”这四步,希望帮到你。
