fortls找不到头文件或模块的根本原因是includepaths仅支持目录层级glob匹配（如${workspacefolder}/include/**），不支持具体文件路径，且需与linter.args中-i参数协同配置，否则符号解析与编译路径脱节。
fortls找不到头文件或模块：includePaths配置失效
不是路径写错了，而是glob模式只匹配目录，不匹配文件——${workspaceFolder}/include/debug.h这种写法永远失败。VS Code的fortran.linter.includePaths只接受目录层级通配，不是文件路径。
- 正确写法是
"${workspaceFolder}/include/**"（结尾双星号表示递归包含所有子目录） - 多个路径用数组形式，不要拼成字符串：
["${workspaceFolder}/src/**", "/usr/local/include"] - Windows路径中反斜杠必须转义或改用正斜杠：
"C:/projects/mylib/include/**"，别写"C:projectsmylibinclude**" - 如果用
#include "math_constants.f90"，确保该文件真正在include/**能扫到的某个子目录里，而不是平级放在根目录
gfortran -I参数和VS Code设置不一致导致编译通过但lint报错
你在终端用gfortran -I./inc main.f90能编译成功，但VS Code里仍标红“Can't find module ‘utils’”，说明linter没读到你手动写的-I参数。
- VS Code的linter默认不复用你终端里的编译命令，它只认
fortran.linter.includePaths和fortran.linter.args - 把
-I参数显式塞进linter args："fortran.linter.args": ["-I./inc", "-I./src"] - 注意：
fortran.linter.args和fortran.linter.includePaths是并行生效的，前者传给编译器，后者供语言服务器做符号解析，两者都得配 - 若项目用了预编译头（如
#include "config.h"），还要确认config.h在includePaths覆盖范围内，否则fortls连宏定义都解析不了
跨平台路径映射失败：WSL/macOS/Windows混用时模块路径错乱
你在WSL里开发，use, intrinsic :: iso_c_binding正常，但一同步到Windows主机就报“module not found”，不是Fortran标准问题，是路径映射没对齐。
- WSL路径
/home/alice/project/src在Windows资源管理器里显示为\wsl$Ubuntuhomeliceprojectsrc，但VS Code Windows版不会自动识别这个映射 - 解决方案：统一用WSL内路径配置，且在Windows版VS Code里启用WSL远程扩展，而不是直接打开
\wsl$...路径 - macOS用pyenv管理Python、又装了fortls时，
fortran.fortls.path必须指向~/.pyenv/shims/fortls或实际可执行文件路径，不能依赖which fortls——因为GUI启动的VS Code看不到shell的pyenv环境 - 模块搜索顺序：先查
fortran.linter.includePaths，再查.mod文件所在目录（默认是./build），最后才 fallback 到编译器内置路径；缺任何一层都会中断
调试时变量名丢失：-g编译但GDB找不到源码行
你写了gfortran -g -I./inc -o app main.f90，launch.json也指定了program路径，但F5调试时断点灰色、变量面板空，根本原因常是路径映射没穿透到debugger。
- GDB需要源码路径和二进制里记录的路径完全一致；如果编译时在
/tmp/build目录下执行，但VS Code打开的是/home/user/proj，GDB就找不到main.f90 - 解决方法：统一在项目根目录编译，或用
gfortran -g -frecord-gcc-switches -o app main.f90让调试信息带绝对路径 - launch.json里加
"sourceFileMap": { "/tmp/build/": "${workspaceFolder}/" }做路径重映射（仅当必须在临时目录编译时才用） - 别依赖Code Runner插件生成的
-o $fileNameWithoutExt——它不带-g，也不控制工作目录，调试时基本不可靠
includePaths只影响符号解析，不影响实际编译；而linter.args传给编译器，却不一定被fortls读取——这两者必须手工对齐，没有自动桥接。
