Uvicorn的reload_excludes对结构相同的某目录失效，但对另一目录正常工作

兄弟，我之前也踩过几乎一模一样的坑，明明两个目录结构、配置看起来完全一致，结果一个能正常排除重载，另一个就是死活不听使唤，真的挺闹心的😅。我当时折腾了好一阵才找到原因，给你分享几个最可能的排查方向：

1. 先死磕路径拼写和大小写（最容易忽略的坑） #

别笑，我当时就是把目录名少打了个字母！尤其是在Linux或macOS系统上，文件名是大小写敏感的——如果你的实际目录是Generated_Tools，但配置里写的是generated_tools，那Uvicorn肯定认不出来。建议你直接复制粘贴目录的绝对路径到排除规则里先测试，比如/home/xxx/src/ai_processing/generated_tools/**，确认生效后再改成相对路径。

2. 试试给路径加上通配符 #

Uvicorn的reload_excludes默认的路径匹配可能没你想的那么“智能”，如果你只写目录名generated_tools，它可能只匹配目录本身，而不会自动排除目录里的所有文件和子目录。改成通配符模式**/generated_tools/**试试——两个星号表示匹配任意层级的目录，这样不管这个目录在项目的哪个位置，里面的任何文件变动都不会触发重载。

我当时就是只写了目录名，结果目录本身的变动被排除了，但里面的文件改了还是会重启，加上通配符就搞定了。

3. 确认当前工作目录和路径基准 #

Uvicorn的相对路径是基于你启动命令的当前工作目录，而不是main.py所在的目录！比如如果你在项目根目录运行uvicorn ai_processing.main:app --reload，那相对路径应该是ai_processing/generated_tools/**；但如果你是进入src/ai_processing/目录后运行uvicorn main:app --reload，那路径就得写成./generated_tools/**。

你可以先在终端里打个pwd（Linux/macOS）或cd（Windows）看看当前在哪，再调整排除规则的路径。

4. 检查Uvicorn版本，必要时升级 #

旧版本的Uvicorn在路径匹配上确实有bug，比如我之前用0.18.x版本的时候，嵌套目录的排除规则就经常失效，升级到最新的稳定版（比如现在的0.24+）之后就正常了。你可以用pip show uvicorn看看版本，不行就pip install --upgrade uvicorn试试。

5. 排查目录是不是软链接 #

如果generated_tools是软链接（符号链接）指向其他目录，Uvicorn的重载机制可能会绕过排除规则——因为它会把软链接的目标目录当成外部路径，不在默认监视范围内，但如果目标目录的文件变动，还是可能触发重载。这种情况要么把软链接改成实际的目录，要么把软链接的目标路径也加到排除规则里。

你可以先按上面的步骤一个个试，尤其是前两个，大概率能解决问题！

内容来源于stack exchange