.gitignore对部署无效，因其仅控制Git跟踪，不影响PhpStorm上传；部署排除需在Deployment→Excluded Paths中单独配置，且路径为前缀匹配、不支持递归通配符。

为什么 .gitignore 对部署没用

部署（Deployment）和版本控制（Git）是两套独立机制。你在项目根目录写的 .gitignore 只影响 Git 是否跟踪文件，完全不参与 PhpStorm 的上传/下载逻辑。即使某个文件被 .gitignore 拦住了，只要它出现在本地项目结构里、且没被 PhpStorm 主动排除，就可能在「Upload to server」时被一并推上去。

真正起作用的是 Deployment 的 Excluded Paths

PhpStorm 的部署排除必须通过 Deployment → Configuration → Excluded Paths 设置，或直接在 Remote Host 工具窗口中右键路径 → Exclude Path。这个操作会写入 .idea/deployment.xml，只对当前部署配置生效。

• 路径匹配是**前缀匹配**：填 vendor/ 会排除所有以该路径开头的文件和子目录
• 支持通配符但**不支持 ** 递归语法**：不能写 **/cache/*，只能写 storage/cache/、var/cache/ 这样明确的路径
• 已排除的路径在 Remote Host 窗口中显示为灰色斜体，且右键菜单里不再有 Upload 选项
• 如果同时配置了多个部署服务器（如 staging / production），需为每个单独设置 Excluded Paths

别混淆 Mark as Excluded 和部署排除

Mark Directory as → Excluded 是 IDE 级别的语义排除，影响索引、搜索、跳转，但**不影响部署行为**——它只是让 PhpStorm “看不见”这个目录，而 Deployment 功能仍会扫描物理路径。所以你得做两件事：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

• 对 node_modules、dist、storage/logs 这类纯构建/运行时产物：右键 → Mark as Excluded（关索引）+ 在 Deployment 配置里加到 Excluded Paths（防上传）
• 对 vendor/autoload.php 这类关键入口文件：**绝不能 Mark as Excluded**，否则类无法识别；但可以只在 Deployment 中排除整个 vendor/ 目录（因为远程服务器通常已通过 composer install 自行生成）
• 如果用了 CI/CD 自动部署，确保 Excluded Paths 里的规则和你的部署脚本逻辑一致，比如别漏掉 .env.local 或 phpunit.xml.dist

常见错误：排除后仍上传了文件

最常被忽略的一点是：Deployment 排除只对「自动同步」和「手动 Upload」生效，但如果你用的是 Tools → Deployment → Upload to… 并勾选了 Upload files automatically，它默认只监听「修改过的文件」，不会检查排除规则。这时候要确认：

立即学习“PHP免费学习笔记（深入）”；

• 是否在 Options 标签页里勾选了 Exclude items not in project（推荐勾上）
• 是否误将路径填在 Mapping 的 Local path 而非 Excluded Paths 选项卡里
• 是否在 Advanced Options 中启用了 Always overwrite files on target，导致排除失效
• 修改 Excluded Paths 后未点击 OK 保存，或未触发一次手动 Sync with Deployed to… 来刷新状态

部署排除不是一次性设置完就高枕无忧的事——尤其是当你切换部署目标（比如从 shared hosting 改到 Docker 容器）时，Excluded Paths 很可能需要重调，因为远程路径结构、权限模型、甚至 PHP 运行环境都变了。