开发中的AL故障排除
Business Central环境中常见部署错误、依赖项和符号下载问题的指南。
在我们的DevSecOps操作中,大多数阻塞问题并非来自代码逻辑错误,而是环境配置故障、版本不匹配或本地IDE(VS Code)与云租户之间的网络通信问题。
这是我们用于在开发和集成阶段即时解决已记录事件的知识库。
执行命令 AL: Download Symbols(或尝试按 F5 生成)时,终端(Output -> AL)会返回如下的大段错误:
[2026-03-24 10:15:23] Sending request to https://api.businesscentral.../v2.0/sandbox/dev/packages?publisher=Microsoft&appName=Application&versionText=27.4.45366[2026-03-24 10:15:24] Error: Not Found[2026-03-24 10:15:24] The request for path ... failed with code NotFound.error AL1022: A package with publisher 'Microsoft', name 'Application', and a version compatible with '27.4.45366' could not be found.这是清单(Manifest)中的版本不同步错误。Business Central 对版本极其严格(version-sensitive)。该错误表明,本地文件 app.json 要求服务器将核心库的版本 27.4.45366 发送给我们。然而,我们指向的 Sandbox(在 launch.json 中配置)安装的是更早版本(例如 25.0.0.0)。由于服务器没有我们要求的版本,因此返回 404。
- < strong >确定服务器版本: < /strong >我们可以通过进入Business Central网站 - > 帮助与支持 - > 关于来检查实际版本。
- 放宽
app.json: 在本地项目中打开文件app.json。 - 降低所需的最低版本。将
"application"和"platform"修改为我们已知安全且通用的版本(例如25.0.0.0)。 - 将执行引擎
"runtime"降级到兼容版本(例如13.0或16.0)。 - 清理缓存: 物理删除隐藏文件夹
.alpackages中的内容。 - 重试: 再次运行
AL: Download Symbols。终端应显示All reference symbols have been downloaded。
事件2:依赖项幽灵错误(“API Reports”)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»尝试下载符号或编译时,系统提示缺少我们无法定位的特定依赖项,例如:A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found。
VS Code 通过 AL: Go! 初始化项目时,有时会在 app.json 的 "dependencies" 块中注入非常特定的模块依赖(例如高级财务模块)。如果我们的 Sandbox 服务器未安装该特定的 Microsoft App,则整体打包将连锁失败。
我们需要清理项目的依赖项。
- 打开
app.json。 - 查找数组
"dependencies": [ ... ]。 - 如果我们开发的是通用集成或简单 API,则完全删除奇怪的依赖块(例如
API Reports - Finance),将数组留空[],或仅保留我们公司自身的关键依赖。 - 清除
.alpackages的缓存并重新下载符号。
事件3:文件夹和命名法的误区(CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»团队疑问: “如果项目根文件夹(例如 Consulta_Datos_Comercial)未按 camelSensitive / CamelCase 书写,AL 编译器会报错吗?”
DevSecOps 技术说明
Sección titulada «Aclaración Técnica DevSecOps»明确的回答是否。AL 编译器对 Windows 文件夹名称的大小写或格式不敏感。
- 操作系统文件系统:Visual Studio Code 和 Windows 对路径是
C:/Proyectos/Consulta_Datos还是c:/proyectos/cOnSuLtAdAtOs并不关心。 - 编译器行为:一旦我们发出编译(Build)命令,引擎就会仅根据
app.json内声明的元数据打包内容(属性"name"和"publisher")。本地目录名会被忽略,对云服务器而言无关紧要。
命名建议:我们在目录中使用 Snake_Case(下划线)约定(Entradas_Salidas_AL),完全是为了 Git 仓库中的人类可读性和视觉整洁,并非编译器的技术要求。
- ✓ 清理:在对
app.json进行结构性更改时,预先清空.alpackages文件夹。 - ✓ 验证: 在清单中声明的依赖套件与云中安装的扩展之间绝对一致。
- ✓ 跟踪: 监控 VS Code 的“AL 语言”输出通道,以精准诊断网络错误。

