如果你的IAR工程是从同事那里拷来的双击打开后一编译满屏全是fatal error: xxx.h: No such file or directory那基本可以断定工程里的头文件路径写的是绝对路径在你电脑上根本不存在那个目录。这个问题干嵌入式的人应该都遇到过。我刚工作那会儿接手的第一个项目就是这类工程——源码齐全、目录整齐就是编译不过去。后来发现Additional include directories里全是C:\Users\旧同事的名字\Desktop\...这种写法别说换电脑了就算把工程从C盘挪到D盘都能干废一片路径。这篇文章就围绕IAR的**Additional include directories附加包含目录怎么用相对路径来配置以及IAR内置变量$PROJ_DIR$**的含义、用法和实际搭配把路径配置这件事彻底讲清楚。看完之后你不仅知道怎么填还能理解为什么这么填遇到路径问题也能自己排查。1. 被绝对路径坑过的工程先看一个典型翻车现场1.1 拷个工程换个电脑编译直接挂掉我拿一个典型的STM32F103C8T6 FreeRTOS工程举例。A同事在自己电脑上开发得好好的工程文件拷给B同事B同事双击打开Project.eww工作区编译啪一下出来几百个错误Fatal Error[Pe1696]: cannot open source file FreeRTOS.h Fatal Error[Pe1696]: cannot open source file task.h Fatal Error[Pe1696]: cannot open source file stm32f1xx_hal.h ...不懂的人以为代码有问题懂的人一看就知道头文件路径没找到。打开Project - Options - C/C Compiler - Preprocessor找到Additional include directories那一栏内容长这样C:\Users\zhangsan\Desktop\STM32_FreeRTOS\Middlewares\Third_Party\FreeRTOS\Source\include C:\Users\zhangsan\Desktop\STM32_FreeRTOS\Middlewares\Third_Party\FreeRTOS\Source\portable\GCC\ARM_CM3 C:\Users\zhangsan\Desktop\STM32_FreeRTOS\Drivers\CMSIS\Include C:\Users\zhangsan\Desktop\STM32_FreeRTOS\Drivers\STM32F1xx_HAL_Driver\Inc ...问题一目了然。这些路径全部绑定在C:\Users\zhangsan\Desktop\这个前缀下到了B同事的电脑上用户名对不上、盘符对不上、目录层级也可能对不上编译器去那些位置找头文件自然全部扑空。1.2 绝对路径为什么在工程里活不长用绝对路径在单机单用户场景下当然能用但它有几个很明显的短板机器迁移失效。这是最普遍的。无论是换电脑、换硬盘还是把工程从一个目录挪到另一个目录只要有任何一个层级发生变化路径就断了。团队协作困难。团队成员之间的工程目录习惯几乎不可能完全统一。有人喜欢放桌面有人放D盘有人放F盘代码仓库绝对路径让每个人的工程配置都不一样互相拷贝之后都要手动改一堆路径浪费时间还容易漏。版本管理不友好。工程一旦放进Git/SVN.ewp文件里记录的绝对路径会成为每个人的本地差异点。同一个工程文件在不同人手里内容不一样合并代码时经常出现莫名其妙的冲突实际上就是路径不一致。不可重复构建。严谨来说一个可交付的工程应该做到在哪里都能编译。绝对路径让构建依赖具体的计算机环境这本身就违背了工程化项目的基本要求。所以正确做法就是让路径跟着工程走不管工程放在哪里路径都能解析到正确位置。这就引出了标题里的两个知识点相对路径和**$PROJ_DIR$变量**。2. 动手前先搞懂IAR是怎么找到头文件的2.1 预处理器的文件搜索顺序很多人一上来就闷头改路径改了半天还是报错因为他没搞明白IAR编译时到底按什么顺序去找头文件。这里把机制讲透。当编译器遇到#include FreeRTOS.h这行代码时预处理器会按照一套固定的搜索顺序在文件系统中查找当前源文件所在目录。这个不需要你配置天然生效。编译选项里通过-I或--include指定的目录。IAR的Additional include directories就是往这个列表里添加目录。通过环境变量或IAR自带标准目录指定的位置。通常是一些stdint.h之类的标准库头文件会用到。搞清楚这个顺序后你就明白了Additional include directories的作用就是扩展第二级搜索目录。这就像是给编译器开了一张寻宝地图告诉它目标头文件可能藏在哪些目录下而不是只靠当前文件目录碰运气。这里面还有一个容易忽略的点在IAR工程里C/C编译器和汇编器Assembler是两套独立的编译前端头文件搜索路径要分别配置。C编译器需要找.h汇编器同样需要尤其那些写了汇编启动文件startup_stm32f103xb.s的工程如果汇编器那边没配好同样会报cannot open source file stm32f1xx.h。很多人只改了C/C Compiler那一栏汇编器没动编译照样报错还以为自己的配置方法有问题。2.2 相对路径和$PROJ_DIR$是两码事这个必须说清楚因为网上很多教程把这两个混为一谈实际上它们的解析基准完全不同。IAR中常见的相对路径写法比如..\..\Middlewares\Third_Party\FreeRTOS\Source\include这种写法是相对于当前工作目录来解析的。IAR默认情况下工作目录就是工程文件.ewp所在的目录所以大多数时候看起来和相对于工程目录效果一样。但问题在于当前工作目录不是一个稳定可靠的基准。在某些场景下——比如你从命令行调用IAR编译器、在构建脚本里指定了不同的工作目录、或者IDE在特定版本中切换了默认工作路径——相对路径的基准就可能变化路径解析结果就不对了。而$PROJ_DIR$是IAR的内置变量它始终解析为当前.ewp工程文件所在的完整目录路径。不管你从哪里启动IDE、工程放在哪个盘、工作目录在哪$PROJ_DIR$指向的永远是.ewp文件在哪它就在哪。理解了这一点你就会明白为什么工程界的主流做法是用$PROJ_DIR$搭配相对路径使用——因为这种方案既保留了相对路径随工程移动的灵活性又通过变量把基准固定死从根本上消除了歧义。写法解析基准可靠性推荐度C:\Users\...绝对路径无基准写死换机器必挂不推荐..\..\Middlewares\...纯相对路径当前工作目录通常能用但可能受启动方式影响可用但不够严谨$PROJ_DIR$\..\..\Middlewares\...变量固定为工程目录稳定可靠随工程移动强烈推荐3. $PROJ_DIR$ 的完整用法手册3.1 $PROJ_DIR$ 解析规则与常见组合写法$PROJ_DIR$是IAR内置变量中最常用的一个它代表工程文件.ewp所在目录。在IAR的Anywhere路径配置输入框中你可以直接输入以$PROJ_DIR$开头的路径表达式。假设工程文件位于D:\work\STM32_PROJ\EWARM\Project.ewp那么$PROJ_DIR$就等于D:\work\STM32_PROJ\EWARM在此基础上我们可以通过\和..\组合出各种目标路径。..\表示向上一级目录这个和Windows命令行的cd ..是一个道理。场景一要引用工程同级的某个目录比如工程目录EWARM的兄弟目录Drivers下有个CMSIS\Include从EWARM向上跳一级到STM32_PROJ再进入Drivers\CMSIS\Include写法就是$PROJ_DIR$\..\Drivers\CMSIS\Include场景二要引用工程目录下的子目录比如工程目录EWARM里面有个user子目录直接追加子目录名即可$PROJ_DIR$\user注意$PROJ_DIR$后面可以不加反斜杠直接加子目录名但为了可读性一般会写$PROJ_DIR$\user。实际上两种写法IAR都能正确识别个人建议统一加上\看起来更清晰。场景三多级向上再深入比如向上两级再进入Middlewares写法就是$PROJ_DIR$\..\..\Middlewares\Third_Party\FreeRTOS\Source\include这两个..\..的意思是从EWARM先向上到STM32_PROJ再向上到D:\work然后再往下找Middlewares目录。这里给一个万能换算公式先数清楚目标目录相对于工程目录需要向上跳几级再数向下要进几层中间的..\就是桥后面的目录就是路。除了$PROJ_DIR$IAR还有其他几个内置变量在不同场景下也有价值变量含义典型使用场景$PROJ_DIR$当前工程文件所在目录引用工程目录附近的头文件$PROJ_FNAME$当前工程文件名不含扩展名构建脚本中生成与工程同名的输出文件$TOOLKIT_DIR$IAR软件安装目录引用IAR自带的库或CMSIS头文件$CONFIG_DIR$配置相关目录某些插件或自定义构建步骤3.2 在IAR里填写Additional include directories的具体操作路径写法搞明白了实际操作其实就几步第一步在IAR的Workspace窗口里右键选中你的工程名比如Project - Debug在弹出的菜单中选择Options。第二步在Options对话框左侧的Category树中展开C/C Compiler选中Preprocessor。第三步在右侧的Additional include directories (one per line)输入框中逐行输入路径。这是关键点——一行写一个路径不要用分号、逗号分隔。很多新手在这里踩坑因为Keil的习惯是用分号分隔IAR不是。比如这样一个四行配置$PROJ_DIR$\user $PROJ_DIR$\..\Drivers\CMSIS\Include $PROJ_DIR$\..\Drivers\STM32F1xx_HAL_Driver\Inc $PROJ_DIR$\..\Middlewares\Third_Party\FreeRTOS\Source\include第四步如果你使用了汇编启动文件左侧Category中还要找到Assembler - Preprocessor在对应的Additional include directories中也加上必要的路径。第五步如果工程有多个配置Debug、Release建议在Options对话框左上角的Configuration下拉框中选择All configurations一次设置生效免得每个配置重复填。第六步点击OK保存然后重新完整编译一次Project - Rebuild All观察编译输出。3.3 三种典型写法的对比和选型建议为了让你更直观地理解不同写法的差异我列一个对比表写法示例可移植性可靠性维护成本适用场景C:\Users\zhangsan\Project\Drivers\CMSIS\Include差换机器就失效高每个机器都要改仅个人单机开发不推荐..\..\Drivers\CMSIS\Include好通常可靠但依赖工作目录中基准不固定命令行编译、脚本构建时需谨慎$PROJ_DIR$\..\..\Drivers\CMSIS\Include好稳定可靠低一次配置到处可用所有场景尤其团队协作个人建议直接选用$PROJ_DIR$写法。它牺牲的只是输入时多敲几个字符换来的是工程在任何机器、任何目录下都能稳定编译。还需要补充一点IAR对正斜杠和反斜杠都支持。比如$PROJ_DIR$/../Drivers/CMSIS/Include也能用。但Windows生态下大家约定俗成用反斜杠而且反斜杠在IAR配置文件里不需要转义所以统一用\就好了。我自己用反斜杠用了很多年没出过问题。4. 实战演练把STM32F103 FreeRTOS工程改成搬不走的路径配置4.1 先规划一个可移植的目录结构路径设置要合理基础是工程目录本身要规划好。我常用的STM32工程目录结构长这样分享出来给你做参考STM32_PROJ/ ├── App/ │ ├── inc/ │ └── src/ ├── BSP/ │ ├── inc/ │ └── src/ ├── Drivers/ │ ├── CMSIS/ │ │ ├── Include/ │ │ └── Device/ │ ├── STM32F1xx_HAL_Driver/ │ │ ├── Inc/ │ │ └── Src/ ├── Middlewares/ │ └── Third_Party/ │ └── FreeRTOS/ │ ├── Source/ │ │ ├── include/ │ │ ├── portable/ │ │ └── src/ ├── EWARM/ │ ├── Project.ewp │ ├── Project.eww │ └── settings/ └── output/这样的优势很明确所有源码都在工程根目录下有规律地分布工程文件单独放进EWARM目录。这样从EWARM目录出发向上一次就能到达所有源码的入口STM32_PROJ路径关系非常清晰。如果你不把工程文件单独放一个文件夹而是直接放在根目录那么路径写起来会短一些不需要..\但整个目录会显得杂乱而且和很多固件库模板、标准化工程结构不一致建议还是单独建一个工程文件目录。4.2 改造步骤逐项替换绝对路径现在开始改。打开之前那个路径全废的工程进入Options - C/C Compiler - Preprocessor把Additional include directories里的内容按以下步骤改造。第一步备份原配置。把所有旧的绝对路径复制到一个文本文件里存着万一改乱了还能还原。第二步逐条转换。以这条绝对路径为例D:\work\STM32_PROJ\EWARM\..\Drivers\CMSIS\Include把前面的绝对前缀D:\work\STM32_PROJ\EWARM替换成$PROJ_DIR$得到$PROJ_DIR$\..\Drivers\CMSIS\Include这里有个视错觉绝对路径里已经包含了\..\Drivers\CMSIS\Include怎么换了个前缀就变成相对引用了原理很简单D:\work\STM32_PROJ\EWARM\..\Drivers的含义就是从EWARM向上回退再进入Drivers我们只是把变量替换了固定前缀而已。第三步所有路径都替换完后对照你的目录结构检查一遍确认每个目标目录真实存在。可以在Windows资源管理器里直接输入$PROJ_DIR$对应的绝对路径去验证。第四步检查汇编器路径。如果你的工程包含.s汇编启动文件进入Assembler - Preprocessor按同样的方法配置。实际开发中我见过太多人把这个漏掉了。第五步检查其他模块。如果你的工程还用了C-SPY调试器的某些插件需要路径或者链接器配置里引用了外部文件路径也一并检查。不过绝大多数情况下只要C编译器和汇编器的include路径正确编译阶段就不会有路径问题。改造完成后的Additional include directories大概长这样$PROJ_DIR$\..\App\inc $PROJ_DIR$\..\BSP\inc $PROJ_DIR$\..\Drivers\CMSIS\Include $PROJ_DIR$\..\Drivers\STM32F1xx_HAL_Driver\Inc $PROJ_DIR$\..\Middlewares\Third_Party\FreeRTOS\Source\include $PROJ_DIR$\..\Middlewares\Third_Party\FreeRTOS\Source\portable\GCC\ARM_CM34.3 验证把整个工程挪到新目录还能编译改造完之后一定要做一次搬家验证这是检验配置是否真正可移植的关键步骤。把整个STM32_PROJ文件夹复制一份放到一个完全不同的位置比如从D:\work\挪到C:\temp\或者放到U盘根目录下打开副本里的.eww文件直接Rebuild All。如果编译0 error 0 warning排除掉原本代码就有的warning说明路径配置真正生效了。如果还有报错大概率是遗漏了某个模块的路径或者某个路径多写了一层..\少写了一层..\按报错信息逐个排查就行。我实测过只要目录结构不变这种工程拷贝到任意机器、任意路径打开就能编译。这也是把工程交给别人时最省心的状态。4.4 一个小细节检查.ewp文件里的存储形式如果你用的是较新的IAR版本比如EWARM 8.x/9.x配置保存后可以直接用文本编辑器打开.ewp文件查找IncludePath关键字你会发现路径是以$PROJ_DIR$\...的形式存储在XML里的。这意味着相对路径是真正写进工程配置内的而不是IAR帮你临时转换的。这么做的好处是工程文件放到版本管理里大家拉下来的是同一份内容不会再因为各自本机的路径差异产生配置冲突。如果你打开.ewp发现里面存的还是C:\Users\...这种绝对路径说明设置没生效回去重新检查是不是填错位置了。5. 路径配置中最容易踩的5个坑和我的解决方案5.1 关于分号、反斜杠和工作目录的坑路径配置技术含量不算高但实际操作中坑不少。把我踩过的和帮别人排查过的坑总结在这里你能绕开就绕开。坑一用分号分隔多个路径。在Keil里多个include路径用分号分隔大家习惯了。到了IAR这里Additional include directories明确要求one per line一行一个不支持分号。如果你把多个路径写在一行用分号分隔IAR会把整行当成一个路径结果一个都找不到。解决办法就是规规矩矩每行一个路径。坑二路径末尾习惯性加反斜杠。某些工具允许末尾带\但IAR对这种写法偶有兼容问题。规范做法是末尾不要加任何符号写到目录名结束。比如$PROJ_DIR$\App\inc不要在inc后面再加\。坑三目录名或盘符带空格。如果工程路径里带空格比如D:\My Projects\STM32\...IAR在某些版本下解析路径时会把空格截断导致路径错误。虽然新版IAR大体上能处理带空格路径但还是建议工程目录和父目录都不要出现空格。如果你控制不了上级目录名比如用户名自带空格可以优先考虑把工程放在一个无空格的路径下。坑四正斜杠反斜杠混用。IAR对两种斜杠都支持但混用会导致可读性差而且个别人在混用时遇到诡异问题。建议统一反斜杠。坑五改了路径没有Rebuild All。很多时候路径改对了但只做了增量编译IAR没有重新扫描头文件依赖看起来还是报错。改完路径后一定要选Project - Rebuild All做一次完整重建排除这种假性报错。5.2 编译报fatal error[lms001]先别查路径这里插一个容易混淆的冷知识。网上搜IAR相关问题时经常能看到fatal error[lms001]: license check failed. use the iar license manager to re...这类报错。这个错误名字里带fatal error很多人误以为是工程配置问题于是疯狂检查路径、配置白白浪费时间。实际上lms001是IAR许可证没有被正确激活导致的跟include路径、工程配置没有半点关系。它的处理方式是打开IAR License Manager重新激活或注册许可证而不是去改工程项目。分清楚报错的类型能帮你少走很多弯路。5.3 我可以直接抄的路径配置规范经过多个项目反复验证我沉淀了一套自己的路径配置规范现在基本所有IAR工程都按这套来目录命名全部用字母、数字、下划线不出现空格和中文字符。工程文件单独放EWARM子目录源码按模块分目录组织。所有include路径一律使用$PROJ_DIR$开头不用纯相对路径更不用绝对路径。Additional include directories中每行一个路径不写分号末尾不加反斜杠。C/C Compiler和Assembler两处的include路径都配置必要时通过All configurations统一设置。配置完成后做一次搬家验证把工程文件夹整个挪到新路径下重新编译一遍确认可移植。涉及IAR自带的头文件时考虑使用$TOOLKIT_DIR$变量而不是写死安装路径这样整个团队即使IAR安装位置不同也能正常编译。在工程目录中新增源码目录后第一时间把include路径补上别等到编译报错再来返工。5.4 最后再分享一个小技巧排查路径问题时IAR的预处理输出很有用。在Options - C/C Compiler - Preprocessor中勾选Preprocessor output to file编译后会在输出目录生成预处理后的.i文件。打开这个文件看文件头部编译器会以注释形式列出实际打开的头文件路径。如果你不确定某个头文件到底是从哪个目录被找到的这个文件能直接给你答案。比如你怀疑FreeRTOS.h被include到了旧版本的路径看.i文件头部就能确认实际加载的是哪个路径下的版本。这个小技巧在排查头文件版本不对明明改了代码却不生效这类疑难杂症时特别好用。路径配置这件事说难不算难说简单又确实容易在细节上栽跟头。但只要理解了$PROJ_DIR$的本质——把路径基准牢牢锚定在工程文件所在目录大部分路径相关的问题就已经解决了一大半。剩下的就是把好习惯固化下来让每次新工程都从一套干净、可移植的路径配置开始。