部署或检索源报错：文件未在sfdx-project.json包目录中配置

云上老周

2026-8-26

问题现象

原有操作习惯：右键点击Apex文件可直接执行部署、检索元数据操作，此前运行无异常
故障表现：近期所有项目执行上述操作均触发统一报错，新建空白测试项目仍可复现问题
报错原文：

Error deploying or retrieving source: The file or directory that you tried to deploy or retrieve isn't in a package directory that's specified in your sfdx-project.json file. Add this location to your "packageDirectories" value, or deploy or retrieve a different file or directory.

报错中文释义：部署或检索源文件失败：当前操作的文件/目录未被纳入sfdx-project.json配置文件中packageDirectories字段指定的包路径范围，请将对应路径添加到该配置项，或选择合法路径下的文件执行操作。

修复方案

按优先级从高到低排查，所有项目/新建项目都报错的场景优先从全局配置、扩展故障查起：

校验项目配置有效性
打开项目根目录下的sfdx-project.json，确认packageDirectories字段包含你存放Apex代码的目录路径，标准默认项目配置参考如下：
```
{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true
    }
  ],
  "namespace": "",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "61.0"
}
```
如果你自定义了代码存放目录（比如src、custom-app等），需要把对应路径补充到packageDirectories数组中。
修复Salesforce VS Code扩展故障
新建项目也报错基本可以排除单项目配置问题，大概率是扩展本身异常：
- 打开VS Code扩展面板，找到Salesforce Extension Pack执行卸载
- 完全关闭VS Code，结束后台所有VS Code相关进程后重新启动
- 安装最新稳定版扩展包，重启VS Code后重试操作
- 如果是近期更新扩展后立刻出现问题，可直接安装v58.14.0稳定版本回退，规避新版本路径识别的已知bug
- 重装后仍异常的，打开扩展设置，勾选Salesforce Deploy: Detect Workspace Root选项，强制扩展从工作区根目录读取配置文件
修复CLI识别异常
在项目根目录打开终端，依次执行以下命令：
```
sfdx update
sfdx config:set restDeploy=false
```
先将Salesforce CLI升级到最新稳定版修复已知路径识别bug，再关闭REST部署模式，改用标准元数据API执行部署检索操作。
修正工作区打开方式
必须直接打开包含sfdx-project.json文件的项目根目录作为VS Code工作区，不要打开根目录的上层文件夹，也不要在多根工作区中嵌套加载项目，否则扩展无法定位到根目录配置文件，会误判文件路径非法。

内容的提问来源于stack exchange，提问作者Walker