对 UiPath CLI 进行故障排除

如果您在使用 UiPath CLI 时遇到问题，请考虑以下故障排除方案。

与.NET版本相关的问题

说明:

如果系统上未安装（或缺少）.NET 框架的正确版本，您可能会遇到 UiPath CLI 任务和管道操作问题。

发生此问题时，您可能会遇到以下错误消息：

  You must install or update .NET to run this application.
  App: C:\Program Files (x86)\UiPath CLI\UiPath.CLI.Windows.23.10.8894.39673\tools\uipcli.exe
  Architecture: x64
  Framework: 'Microsoft.NETCore.App', version '6.0.0' (x64)
  .NET location: C:\Program Files\dotnet
  The following frameworks were found:
  8.0.5 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  8.0.8 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

或者

  An error occurred trying to start process 'dotnet' with working directory 'C:\Users\Public\UiPathDevOpsScripts\uipathcli-23.10\tools'. The system cannot find the file specified. Failed to run the command. UiPath.CommandLine.Exceptions.CommandException: Packaging failed due to one or more errors.
  Message: An error occurred trying to start process 'dotnet' with working directory 'C:\Users\Public\UiPathDevOpsScripts\uipathcli-23.10\tools'. The system cannot find the file specified.
  Error at: System.Diagnostics.Process.StartWithCreateProcess(ProcessStartInfo startInfo)

Remedy:

必须确保安装正确的 .NET 版本。

有关 CLI 和.NET版本兼容性矩阵，请参阅“先决条件”部分。

与连接字符串密码中特殊字符相关的问题

在大多数情况下，连接密码都包含在单引号 (') 中。但是，当密码包含特殊字符（例如`或$时，则需要采用不同的方法。

在这些情况下，密码的格式必须为 \`"<password>\`"，并将 <password> 替换为实际密码。此外，您还必须遵守下表中详述的转义规则：

ADDU 中的原始格式	PowerShell 字符串中的转义格式
cn=James $ Smith	"cn=James `$ Smith"
cn=Sally Wilson + Jones	"cn=Sally Wilson \+ Jones"
cn=William O'Brian	"cn=William O'Brian"
cn=William O`Brian	"cn=William O``Brian"
cn=Richard #West	"cn=Richard #West"
cn=Roy Johnson$	"cn=Roy Johnson$"

示例：

假设原始密码为 7'8:<=XMe$y[@vC?_4ZeY8c-~y'W!1dU4gnczuf'/p>j<I。遵循特殊字符转义规则，它将变为：Password=\`"7'8:<=XMe`$y[@vC?_4ZeY8c-~y'W!1dU4```gnczuf'/p>```j<I\`"。

与管道性能低下相关的问题

说明:

在 CI/CD 管道中进行打包操作时，您可能会遇到性能下降的情况。这种延迟通常发生在 NuGet 还原阶段，在此阶段，UiPath CLI 会解析直接活动依赖项和可传递活动依赖项。

此问题通常会影响从干净环境启动的托管 CI 智能体（GitHub Actions、Azure DevOps、GitLab、Jenkins）。除非显式配置，否则 NuGet 全局包缓存不会在运行之间保留，这需要完整下载每个作业的所有依赖项。

NuGet 缓存位置：

• Linux/macOS： ~/.nuget/packages
• Windows： %UserProfile%\.nuget\packages

影响因素：

未提供自定义nuget.config时，NuGet 会按顺序查询所有默认源：

https://api.nuget.org/v3/index.json
https://pkgs.dev.azure.com/uipath/Public.Feeds/_packaging/UiPath-Official/nuget/v3/index.json
https://gallery.uipath.com/api/v3/index.json
https://uipath.pkgs.visualstudio.com/Public.Feeds/_packaging/UiPath-Internal/nuget/v3/index.json

NuGet 不会跳过速度慢或无法访问的订阅源。它会等待响应或超时，然后再继续处理下一个来源。对于每个缺少的包，NuGet 会执行以下操作：

1. 缓存查找（对于新智能体为空）。
2. 按顺序对每个已配置订阅源的探测器。
3. 如果订阅源无响应，则等待或超时。
4. 找到可访问的来源后执行下载。

延迟时间与依赖项的数量成正比。如果没有缓存，则对每次管道运行上的每个包重复此过程。

补救措施：

要提高还原性能，请执行以下操作：

1. 使用修剪后的nuget.config文件，该文件仅包含可从构建代理访问的订阅源。有关配置详细信息，请参阅“管理 NuGet 订阅源” 。

2. 在管道运行之间为 NuGet 全局包缓存配置缓存持久性。

   Azure DevOps（Windows 代理）示例：

   - task: Cache@2
     displayName: "NuGet Cache"
     inputs:
       key: 'nuget | "$(Agent.OS)" | packages'
       restoreKeys: |
         nuget | "$(Agent.OS)"
       path: '$(UserProfile)\.nuget\packages'
   

3. 如果环境需要，请使用具有持久存储的自托管运行器。

与 .NET Runtime 可用性相关的问题

说明:

您可能会遇到 UiPath CLI 无法在生成代理上找到 .NET Runtime 的问题，从而导致如下错误：

dotnet is not recognized

即使已在系统上正确安装 .NET，当运行生成代理的服务帐户未继承计算机PATH环境变量时，也会出现此问题。

补救措施：

在执行任何 CLI 命令之前，必须在管道、作业或代理级别显式定义 .NET 安装路径。

Windows 示例：

env:
  PATH: 'C:\Program Files\dotnet;$(PATH)'

备注：

内联脚本对PATH变量的更改不会传播到子流程。必须在管道、作业或代理级别配置路径，以确保 UiPath CLI 可以在默认和自定义安装方案中找到 .NET 运行时。

与代理和 SSL 证书验证相关的问题

说明:

在具有 SSL 检查代理的企业环境中运行 UiPath CLI 时，您可能会遇到 SSL 证书验证错误。常见错误消息包括：

self-signed certificate in certificate chain
The SSL connection could not be established, see inner exception

发生此问题的原因是，即使操作系统信任代理的证书，基于节点的工具（包括 UiPath CLI 和 NuGet 任务）也不会读取 Windows 或 Linux 系统证书存储。

补救措施：

要解决企业版环境中的证书验证问题，请执行以下操作：

1. 配置代理环境变量。在执行任何 CLI 或节点任务之前，在管道、作业或代理级别设置以下变量：

   HTTP_PROXY
   HTTPS_PROXY
   

   这可确保构建代理和所有子流程继承代理配置。

2. 配置 Node.js 的证书信任。如果代理使用私有或自签名证书颁发机构 (CA)，则必须以.pem格式导出 CA 证书，并将 Node.js 配置为信任该证书：

   NODE_EXTRA_CA_CERTS=<path-to-pem>
   

   Windows 示例：

   NODE_EXTRA_CA_CERTS=C:\agent\certs\myCA.pem
   

   Node.js 将在启动时加载此证书文件，从而成功完成 HTTPS 调用，而不会出现证书错误。

重要提示：

您必须在管道、作业或智能体级别声明这些环境变量。在单个 PowerShell 或 Bash 脚本步骤中设置它们不会将值传播到 Node.js 子流程。

与 PowerShell 参数处理相关的问题

applicationSecret 参数中存在特殊字符

说明:

在 PowerShell 脚本中使用--applicationSecret参数时，特殊字符（例如$ 、 ` 、 !等）可能会导致身份验证失败或意外行为。发生这种情况是因为当这些字符用双引号括起来时，PowerShell 会将这些字符解释为特殊运算符。

例如，PowerShell 将$视为变量扩展运算符，因此双引号中的mySecret$123等密码变为mySecret123 （如果$123未定义）或替换为意外的值。

常见症状：

• 使用有效凭据进行的身份验证失败
• 错误:“未经授权”或“凭据无效”
• 使用相同的命令在其他 Shell 中运行时，行为不一致

补救措施：

传递--applicationSecret参数时，请使用单引号 ( '' ) 代替双引号 ( "" ) 。单引号会阻止 PowerShell 解释特殊字符：

# Correct - single quotes treat the string literally
uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
  -A "myOrg" `
  -I "app-id" `
  -S 'mySecret$123!@#' `
  -o "MyFolder"

# Incorrect - double quotes allow variable expansion
uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
  -A "myOrg" `
  -I "app-id" `
  -S "mySecret$123!@#" `
  -o "MyFolder"

替代方法：

1. 将密码存储在环境变量中：

   $env:APP_SECRET = 'mySecret$123!@#'
   uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
     -A "myOrg" `
     -I "app-id" `
     -S $env:APP_SECRET `
     -o "MyFolder"
   

2. 使用 CI/CD 平台密码管理：

   • Azure DevOps：管道密码变量
   • GitHub Actions：密码
   • Jenkins：凭据插件

提示：

此问题特定于 PowerShell。在 Bash、CMD 或其他 Shell 中，标准引用规则适用。

与身份验证相关的问题

错误：“未经授权”或“403 Forbidden”

说明:

执行与 Orchestrator 交互的 UiPath CLI 命令时，可能会收到身份验证错误。

可能的原因：

• 外部应用程序 ID 或密码不正确
• 未将所需的作用域分配给外部应用程序
• 使用-A参数指定的组织名称与您的 Orchestrator 组织不匹配

补救措施：

• 在 Orchestrator 中的“管理员” → “外部应用程序”下，验证外部应用程序凭据。
• 确认已将所有必需的作用域分配给该外部应用程序。有关所需作用域的完整列表，请参阅“身份验证和作用域” 。
• 确保组织名称完全匹配（区分大小写）。

错误：“无效的作用域”

说明:

您可能会遇到指示指定的应用程序作用域无效或无法识别的错误。

可能的原因：

• 使用了不正确的作用域名称。
• Orchestrator 作用域和解决方案作用域在同一参数中混合使用。

补救措施：

• 对于“解决方案”操作，请使用以下作用域： AutomationSolutions 、 Solutions.Deployments 、 Solutions.Packages及其各自的子作用域。
• 不要在相同的--applicationScope参数中将 Orchestrator 作用域（例如OR.Jobs ）与解决方案作用域混合使用。

错误：“证书验证失败”

说明:

在具有代理服务器的环境中执行 CLI 命令时，可能会发生 SSL 证书验证错误。

补救措施：

• 按照代理和 SSL 证书验证相关问题中的说明配置NODE_EXTRA_CA_CERTS环境变量。
• 确保在管道或智能体级别配置代理变量（ HTTP_PROXY 、 HTTPS_PROXY ）

与打包和部署相关的问题

错误：“版本是必填项”

说明:

尝试打包不指定版本号的解决方案时，您可能会遇到此错误。与独立项目不同，解决方案不会自动递增其版本。

补救措施：

执行 pack 命令时必须提供--version参数：

uipcli solution pack <solution-path> --version 1.2.3 --output <output-folder>

错误：“版本格式无效”

说明:

当版本号不遵循所需的语义版本控制格式时，会发生此错误。

补救措施：

使用以下格式： MAJOR.MINOR.PATCH （例如1.0.0 、 2.3.45 ）

以下格式无效:

• 1.0 （缺少补丁组件）
• 1.0.0.0 （组件过多）
• v1.0.0 （包含非数字前缀）
• 1.0-beta （包含后缀）

错误：“无法解析依赖项”

说明:

此错误表明解决方案的依赖项在打包之前尚未恢复。

补救措施：

在尝试打包之前执行restore命令：

uipcli solution restore <solution-path> --restoreFolder <output-folder>
uipcli solution pack <solution-path> --version 1.2.3 --output <output-folder>

错误：“未找到路径”

说明:

找不到指定的解决方案路径。

补救措施：

验证<solution-path>参数是否指向有效的解决方案文件夹或.uipx文件。

错误：“未找到包”

说明:

尝试引用解决方案中不存在的解决方案包时，会发生此错误。

可能的原因：

• 包未成功上传。
• 包名称或版本不正确。
• 该命令指向错误的租户或组织。

补救措施：

• 验证是否已使用uipcli solution upload-package上传了包。
• 确认包名称和版本正确无误（请注意，这些值区分大小写）。
• 确保-T参数指定正确的租户。

错误：“未找到文件夹”

说明:

指定的文件夹在 Orchestrator 中不存在或无法访问。

可能的原因：

• Orchestrator 中不存在此文件夹名称。
• 权限不足，无法访问文件夹。
• 该文件夹存在于其他租户中。

补救措施：

• 验证 Orchestrator 中存在使用-f参数指定的文件夹名称。
• 确认您具有部署到此文件夹的必要权限。
• 确保该文件夹位于正确的租户中。

错误：“部署已存在”

说明:

目标文件夹中已存在具有指定名称的部署。

补救措施：

• 为每个部署使用唯一的部署名称（例如，在名称中包含版本号或时间戳）。
• 创建新部署之前卸载现有部署。有关详细信息，请参阅“卸载部署” 。

错误：“未找到部署”（激活期间）

说明:

尝试激活不存在的部署时，会发生此错误。

可能的原因：

• 在运行deploy-activate之前未执行deploy命令。
• 部署名称不正确。
• 部署操作失败。

补救措施：

• 在运行uipcli solution deploy-activate之前，验证您已执行uipcli solution deploy 。
• 确认部署名称完全匹配（请注意，部署名称区分大小写）。
• 审核命令执行日志，确保部署操作成功完成。