Ir al contenido

开发中的AL故障排除

Business Central环境中常见部署错误、依赖项和符号下载问题的指南。

0阅读

在我们的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。

  1. < strong >确定服务器版本: < /strong >我们可以通过进入Business Central网站 - > 帮助与支持 - > 关于来检查实际版本。
  2. 放宽 app.json: 在本地项目中打开文件 app.json。
  3. 降低所需的最低版本。将 "application" 和 "platform" 修改为我们已知安全且通用的版本(例如 25.0.0.0)。
  4. 将执行引擎 "runtime" 降级到兼容版本(例如 13.0 或 16.0)。
  5. 清理缓存: 物理删除隐藏文件夹 .alpackages 中的内容。
  6. 重试: 再次运行 AL: Download Symbols。终端应显示 All reference symbols have been downloaded。

尝试下载符号或编译时,系统提示缺少我们无法定位的特定依赖项,例如:A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found。

VS Code 通过 AL: Go! 初始化项目时,有时会在 app.json 的 "dependencies" 块中注入非常特定的模块依赖(例如高级财务模块)。如果我们的 Sandbox 服务器未安装该特定的 Microsoft App,则整体打包将连锁失败。

我们需要清理项目的依赖项。

  1. 打开 app.json。
  2. 查找数组 "dependencies": [ ... ]。
  3. 如果我们开发的是通用集成或简单 API,则完全删除奇怪的依赖块(例如 API Reports - Finance),将数组留空 [],或仅保留我们公司自身的关键依赖。
  4. 清除 .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 编译器会报错吗?”

明确的回答是否。AL 编译器对 Windows 文件夹名称的大小写或格式不敏感。

  1. 操作系统文件系统:Visual Studio Code 和 Windows 对路径是 C:/Proyectos/Consulta_Datos 还是 c:/proyectos/cOnSuLtAdAtOs 并不关心。
  2. 编译器行为:一旦我们发出编译(Build)命令,引擎就会仅根据 app.json 内声明的元数据打包内容(属性 "name" 和 "publisher")。本地目录名会被忽略,对云服务器而言无关紧要。

命名建议:我们在目录中使用 Snake_Case(下划线)约定(Entradas_Salidas_AL),完全是为了 Git 仓库中的人类可读性和视觉整洁,并非编译器的技术要求。

  • ✓ 清理:在对 app.json 进行结构性更改时,预先清空 .alpackages 文件夹。
  • ✓ 验证: 在清单中声明的依赖套件与云中安装的扩展之间绝对一致。
  • ✓ 跟踪: 监控 VS Code 的“AL 语言”输出通道,以精准诊断网络错误。