自建Azure DevOps构建Agent无法从$PATH识别nbgv工具

现象说明 #

我有一台自建的Azure DevOps构建Agent，已安装dotnet工具和Nerdbank Git Versioning（nbgv）。通过SSH登录Agent后，可正常定位并运行nbgv：

agent@ip-172-18-0-30:~$ which nbgv
/home/agent/.dotnet/tools/nbgv

agent@ip-172-18-0-30:~$ nbgv -h
Description:
  nbgv v3.7.115+d31f50f4d1

我在Pipeline起始阶段添加了如下脚本，用于检查Agent用户、$HOME环境变量、$PATH环境变量，随后尝试运行nbgv：

steps:
  - checkout: self
    fetchDepth: 0
    persistCredentials: true
  
  - script: |
      echo "Current user: $(whoami)"
      echo "HOME: $HOME"
      echo "PATH: $PATH"
      ls -la $HOME/.dotnet/tools
      dotnet tool list --global
      nbgv get-version

但脚本执行失败，提示nbgv: command not found，完整输出如下：

/usr/bin/bash --noprofile --norc /home/agent/myagent/_work/_temp/976f3776-1157-4b41-a83c-b9a2e0d5e1da.sh
Current user: agent
HOME: /home/agent
PATH: $HOME/.local/bin:/opt/pipx_bin:$HOME/.dotnet/tools:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
total 84
drwxr-xr-x 3 agent agent  4096 Feb 10 13:36 .
drwxr-xr-x 3 agent agent  4096 Feb 10 13:36 ..
drwxr-xr-x 4 agent agent  4096 Feb 10 13:36 .store
-rwxr-xr-x 1 agent agent 72352 Feb 10 13:36 nbgv

Welcome to .NET 8.0!
---------------------
SDK Version: 8.0.405

Telemetry
---------
The .NET tools collect usage data in order to help us improve your experience. It is collected by Microsoft and shared with the community. You can opt-out of telemetry by setting the DOTNET_CLI_TELEMETRY_OPTOUT environment variable to '1' or 'true' using your favorite shell.

Read more about .NET CLI Tools telemetry: https://aka.ms/dotnet-cli-telemetry

----------------
Installed an ASP.NET Core HTTPS development certificate.

To trust the certificate, view the instructions: https://aka.ms/dotnet-https-linux

----------------
Write your first app: https://aka.ms/dotnet-hello-world
Find out what's new: https://aka.ms/dotnet-whats-new
Explore documentation: https://aka.ms/dotnet-docs
Report issues and find source on GitHub: https://github.com/dotnet/core
Use 'dotnet --help' to see available commands or visit: https://aka.ms/dotnet-cli
--------------------------------------------------------------------------------------
Package Id      Version      Commands
-------------------------------------
nbgv            3.7.115      nbgv    
/home/agent/myagent/_work/_temp/976f3776-1157-4b41-a83c-b9a2e0d5e1da.sh: line 6: nbgv: command not found

尽管$HOME为/home/agent，$PATH已包含$HOME/.dotnet/tools，且该目录下存在nbgv，但仍提示命令未找到。

参考我的Agent初始化脚本：

#!/bin/bash

AGENT_USER="agent"
AGENT_HOME="/home/$AGENT_USER"
useradd -m -s /bin/bash $AGENT_USER

export VSTS_AGENT_INPUT_URL=${url}
export VSTS_AGENT_INPUT_AUTH=pat
export VSTS_AGENT_INPUT_TOKEN=${token}
export VSTS_AGENT_INPUT_POOL=${pool}

echo "export VSTS_AGENT_INPUT_URL=${url}" >> $AGENT_HOME/.bashrc
echo "export VSTS_AGENT_INPUT_AUTH=pat" >> $AGENT_HOME/.bashrc
echo "export VSTS_AGENT_INPUT_TOKEN=${token}" >> $AGENT_HOME/.bashrc
echo "export VSTS_AGENT_INPUT_POOL=${pool}" >> $AGENT_HOME/.bashrc

chown -R $AGENT_USER:$AGENT_USER $AGENT_HOME

cd $AGENT_HOME

wget https://vstsagentpackage.azureedge.net/agent/4.248.0/vsts-agent-linux-x64-4.248.0.tar.gz
mkdir myagent && cd myagent
tar zxvf ../vsts-agent-linux-x64-4.248.0.tar.gz
./bin/installdependencies.sh
chown -R $AGENT_USER:$AGENT_USER .
su $AGENT_USER -c './config.sh --unattended'
echo "HOME=$AGENT_HOME" >> .env
./svc.sh install $AGENT_USER

usermod -aG docker $AGENT_USER

./svc.sh start

mkdir -p $AGENT_HOME/myagent/_work
chown -R $AGENT_USER:$AGENT_USER $AGENT_HOME/myagent/_work

原因分析 #

核心问题是**$PATH中的$HOME变量未被实际展开**：

• 从输出可见，PATH里显示的是$HOME/.dotnet/tools，而非解析后的/home/agent/.dotnet/tools。
• Azure DevOps的script任务默认使用bash --noprofile --norc执行脚本，不会加载用户的.bashrc等配置文件；同时Agent服务启动时的环境变量中，$HOME变量没有被解析成实际路径，导致系统无法识别$HOME/.dotnet/tools这个有效路径。
• 虽然dotnet tool list --global能识别nbgv，但直接调用命令时，shell无法解析PATH中的变量占位符，因此找不到可执行文件。

解决方法 #

方案1：直接使用nbgv的绝对路径 #

在Pipeline脚本中直接指定nbgv的完整路径，绕过PATH变量的问题：

/home/agent/.dotnet/tools/nbgv get-version

方案2：在Pipeline脚本中手动展开PATH #

在调用nbgv前，先重新导出包含实际路径的PATH：

export PATH="$HOME/.dotnet/tools:$PATH"
nbgv get-version

方案3：修改Agent的环境变量配置 #

• 编辑Agent目录下的.env文件，将PATH设置为包含实际路径的内容，替换掉带$HOME的占位符：

  PATH=/home/agent/.dotnet/tools:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
  

• 修改后重启Agent服务：./svc.sh restart

方案4：将nbgv安装到系统全局路径 #

安装nbgv时指定系统级的工具路径，这样PATH默认包含该目录，无需依赖用户路径：

dotnet tool install --tool-path /usr/local/bin nbgv

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