终端入口基线：Windows Terminal、PowerShell、bash 与 zsh

终端启动与命令解析Terminal 启动 Shell，Profile 和启动文件塑造 PATH、环境变量与补全；验证必须回到真实进程与命令来源。高清原图

从“终端能运行，IDE 却找不到命令”开始

“终端里能运行，IDE 或 CI 里却找不到命令”，通常不是命令本身坏了，而是启动链不同。窗口由 Terminal 宿主提供，命令由 Shell 解释，环境变量和补全由 Profile 或启动文件装载。把这些对象混在一起，会导致重复安装、PATH 污染、配置放错文件和错误提权。

先用普通用户打开一个新终端，不修改任何配置。选一个已经安装的项目命令，例如 git、node 或 java；没有时使用系统命令即可。第一轮只记录宿主、Shell、命令来源和会话类型，并为稍后可能修改的 $PROFILE、.bashrc 或 .zshrc 建立备份。企业设备若实施脚本签名、执行策略或终端安全管控，也要先找到策略 owner，避免用全局绕过掩盖真实原因。

启动链可以画成四层：

Terminal 宿主
  └─ Profile：决定启动命令、起始目录、环境和外观
       └─ Shell 进程：PowerShell / bash / zsh
            └─ 启动文件：$PROFILE / .bashrc / .zshrc ...
                 └─ PATH、函数、别名、补全和项目命令

Terminal 管理窗口、标签页、字体、快捷键和要启动的命令。Shell 解析命令、维护会话状态并启动子进程。Profile 在 Terminal 层描述“启动哪个 Shell”；Shell 自己的 profile/rc 文件再决定会话初始化。

因此，Windows Terminal 不是 Shell；安装 PowerShell 7 也不会自动替换 Windows Terminal 或卸载 Windows PowerShell 5.1。团队真正要统一的是可诊断的启动契约，而不是主题、字体或个人别名。

安装并识别终端入口

PowerShell 7

PowerShell 7 使用 pwsh，并与 Windows PowerShell 5.1 的 powershell.exe 并行。Microsoft 的 Windows 安装说明 将 WinGet 作为 Windows 客户端的推荐入口；企业批量部署可根据同一页面选择 MSI，便携隔离场景可选择 ZIP。安装前先搜索包身份，再执行安装：

winget search --id Microsoft.PowerShell
winget install --id Microsoft.PowerShell --source winget

安装后关闭并重新打开终端，再验证 pwsh。不要把 powershell.exe 与 pwsh.exe 当成同一个程序，也不要因为 PowerShell 7 已安装就删除仍被旧模块依赖的 Windows PowerShell 5.1。

Get-Command powershell, pwsh -ErrorAction SilentlyContinue |
  Select-Object Name, Source, Version
pwsh -NoLogo -Command '$PSVersionTable.PSVersion'

企业设备可能要求软件中心、离线包或管理员批准。版本通道和支持期限应结合 PowerShell 支持生命周期 选择，项目需要稳定维护窗口时不能简单追随 Preview。

Windows Terminal

Windows Terminal 是宿主。Microsoft 的 安装说明 支持 Microsoft Store、WinGet 等入口；企业设备则使用组织软件分发渠道，不从第三方压缩包覆盖系统目录。安装后先在 Settings 的 Startup 页面确认默认 Profile，再创建一个明确启动 pwsh 的个人 Profile。

示例只展示关键字段，不能直接覆盖完整 settings.json：

{
  "profiles": {
    "defaults": {
      "elevate": false
    },
    "list": [
      {
        "name": "PowerShell 7",
        "commandline": "pwsh.exe -NoLogo",
        "startingDirectory": "%USERPROFILE%"
      }
    ]
  }
}

不要写死 Profile GUID，也不要把所有 Profile 设置为管理员启动。Windows Terminal 会为检测到的 PowerShell 和 WSL 发行版生成动态 Profile；commandline、startingDirectory、hidden、elevate 与 profiles.defaults 的行为以 Profile 常规设置 为准，最终仍要从新标签页检查实际进程。

bash

bash 通常由 Linux 发行版、WSL、macOS 附加环境或开发工具链提供。先识别来源，不要为了得到 bash 从未知站点下载安装器：

type -a bash
bash --version

若系统没有 bash，应通过目标操作系统的官方包管理器安装，并在安装后记录实际路径。包名和受支持版本由发行版仓库决定，不从未知脚本安装同名二进制。

zsh

macOS 的 Terminal 可使用 zsh，实际登录 Shell 仍应按 Apple 的 默认 Shell 管理方法 检查；Linux 可通过发行版官方包管理器安装 zsh。先检查：

whence -v zsh
zsh --version

安装 zsh 不等于已经把它设为登录 Shell，也不等于启用了补全。默认 Shell 的变更受 /etc/shells、账号目录服务和企业管理策略约束，应先确认组织规则。

PowerShell Profile

PowerShell 有多个 Profile 作用域。先让运行时告诉你真实路径：

$PROFILE | Format-List * -Force
Test-Path $PROFILE

需要创建当前用户、当前宿主 Profile 时：

if (-not (Test-Path -LiteralPath $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force | Out-Null
}

Profile 中只放轻量、幂等、无秘密的初始化。不要在每次启动时联网更新工具、输出令牌或递归扫描大型目录。建议把复杂逻辑封装成模块，并对可选工具做存在性判断：

if (Get-Command git -ErrorAction SilentlyContinue) {
  $env:DEV_GIT_AVAILABLE = '1'
}

执行策略不是权限边界的替代品。遇到脚本被阻止时先查看来源：

Get-ExecutionPolicy -List

不要把 Set-ExecutionPolicy Bypass -Scope LocalMachine 写成通用修复。企业 Group Policy 可能覆盖本地设置；正确做法是确认签名、文件来源、策略作用域和组织要求，采用最小作用域变更。

Windows Terminal Profile

Windows Terminal 层配置启动命令和工作目录，Shell 层配置 PATH、函数和补全。WSL Profile 如果主要用于 Linux 开发，应进入 Linux Home，而不是把 Windows %USERPROFILE% 当成相同语义。

示例：

{
  "name": "Project WSL",
  "commandline": "wsl.exe -d <distribution-name>",
  "startingDirectory": "\\\\wsl.localhost\\<distribution-name>\\home\\<user>"
}

<distribution-name> 和 <user> 是占位符。真实 Profile 不应提交个人用户名、企业发行版名称或本机绝对路径到公共仓库。

bash 启动文件

Bash 的读取路径取决于会话类型；GNU 的 Bash Startup Files 给出了 login、interactive 与 non-interactive 三类入口的精确顺序：

会话	主要启动文件
交互式 login	/etc/profile，再读取 ~/.bash_profile、~/.bash_login、~/.profile 中第一个存在且可读者
交互式 non-login	~/.bashrc
非交互脚本	不自动读取 ~/.bashrc，可通过 BASH_ENV 指定文件

如果希望 login Shell 也获得交互配置，通常由 ~/.bash_profile 显式加载 ~/.bashrc：

if [ -f "$HOME/.bashrc" ]; then
  . "$HOME/.bashrc"
fi

不要在 .bashrc 中无条件输出欢迎文字或运行交互命令，因为某些远程和工具调用会受影响。非交互脚本应显式声明依赖，不应依赖开发者个人 .bashrc。

zsh 启动文件

zsh 的核心顺序可以理解为：.zshenv 适用于所有会话，login 会话读取 .zprofile，interactive 会话读取 .zshrc；实际行为还受全局文件、RCS、GLOBAL_RCS 和 ZDOTDIR 影响，完整顺序见 zsh 的 Startup/Shutdown Files。

.zshenv 只放所有 zsh 进程都必须拥有的极少环境变量，避免慢命令和交互输出。.zprofile 适合 login 会话环境初始化。.zshrc 适合交互体验、提示符、别名与补全。

项目脚本不要依赖个人 .zshrc。

查看真实配置根目录：

print -r -- "${ZDOTDIR:-$HOME}"

PATH 与命令解析

PATH 是有顺序的查找列表。验证时既要看变量，也要看解析结果：

$env:PATH -split [IO.Path]::PathSeparator
Get-Command git -All | Select-Object Name, Source, Version

printf '%s\n' "$PATH" | tr ':' '\n'
type -a git
command -v git

print -l ${(s.:.)PATH}
whence -a git

不要把同一工具的多个安装目录反复追加到 PATH。优先使用版本管理器或项目 wrapper，并保证初始化幂等；否则新开几个嵌套 Shell 后 PATH 会不断膨胀。

补全

Bash 补全依赖 compspec、补全函数与 Readline。验证：

type -a complete
complete -p 2>/dev/null | head

zsh 补全通常通过 compinit 初始化，其 autoload、缓存与安全检查属于 zsh Completion System 的运行链路：

autoload -Uz compinit
compinit
whence -v compinit

若 compinit 报目录权限不安全，先用 compaudit 查明问题并修复目录 owner/写权限，不要用跳过安全检查的参数永久掩盖。Oh My Zsh、Homebrew 补全目录和主题框架由各自项目维护，不能用 zsh 官方文档替它们保证兼容。

验证目标是证明“宿主启动了预期 Shell，Shell 读取了预期文件，PATH 指向预期命令，补全可用且新会话仍然成立”。

PowerShell

$PSVersionTable
Get-Command powershell, pwsh -ErrorAction SilentlyContinue |
  Select-Object Name, Source, Version
$PSHOME
$PROFILE | Format-List * -Force
[Environment]::Is64BitProcess
Get-ExecutionPolicy -List
Get-Command git -All -ErrorAction SilentlyContinue |
  Select-Object Name, Source, Version

在 Profile 中临时加入一个无副作用标记：

$env:DEV_PROFILE_LOADED = '1'

关闭所有测试标签页，新开 PowerShell 7，确认：

$env:DEV_PROFILE_LOADED
$PSVersionTable.PSVersion

验证后删除临时标记行并再次打开新会话，确认变量不再出现。这样同时验证了加载与清理。

bash

printf 'declared-shell=%s\n' "$SHELL"
ps -p $$ -o pid=,ppid=,comm=,args=
printf 'flags=%s\n' "$-"
shopt -q login_shell && echo login || echo non-login
type -a bash
type -a git
type -a complete

$SHELL 通常表示账号登录 Shell，不保证等于当前进程。当前进程、参数、$- 和 login_shell 才能共同解释真实会话。

zsh

printf 'declared-shell=%s\n' "$SHELL"
ps -p $$ -o pid=,ppid=,comm=,args=
[[ -o interactive ]] && echo interactive || echo non-interactive
[[ -o login ]] && echo login || echo non-login
print -r -- "${ZDOTDIR:-$HOME}"
whence -a git
whence -v compinit

成功标准：

Terminal Profile 的启动命令与实际进程一致。PowerShell 5.1 与 7 可被明确区分；bash/zsh 的 login 与 interactive 状态可被解释。实际 Profile/rc 文件路径已确认，不靠猜测。

项目命令解析到预期安装位置与版本。补全函数已加载，或明确说明项目不启用补全。新开会话后配置仍生效，IDE 集成终端也能复现。

测试标记已删除，没有遗留执行策略放宽或管理员默认启动。

个人 Profile 不应成为项目唯一入口。仓库应把必须一致的行为放在可审查文件中：

.vscode/
  tasks.json
scripts/
  dev.ps1
  dev.sh
  doctor.ps1
  doctor.sh
docs/development/
  terminal-baseline.md

项目脚本负责稳定命令和错误输出，个人 Profile 只负责找到项目入口。跨平台项目可以提供等价的 dev.ps1 与 dev.sh，或者使用已有跨平台任务运行器；不要在 README 中假设所有人都已配置相同别名。

诊断脚本至少输出：

当前 Shell 名称、版本与进程架构；login/interactive 状态；关键命令的真实解析路径；

项目工作目录；必需环境变量是否存在，但不输出值；代理和证书只输出配置来源，不输出凭证。

CI 与 IDE 不应依赖个人 .bashrc、.zshrc 或 PowerShell Profile。CI 脚本显式声明运行 Shell；IDE Task 显式指定命令和工作目录。开发机能够直接运行同一仓库脚本，才算项目接入完成。

确认当前运行时

$PSVersionTable.PSEdition
$PSVersionTable.PSVersion
$PSHOME
[Environment]::Is64BitProcess

ps -p $$ -o comm=,args=
printf 'flags=%s\n' "$-"
shopt -q login_shell && echo login || echo non-login

ps -p $$ -o comm=,args=
[[ -o interactive ]] && echo interactive
[[ -o login ]] && echo login

重载配置

. $PROFILE

source "$HOME/.bashrc"

source "${ZDOTDIR:-$HOME}/.zshrc"

重载适合验证小改动，但不能替代新开会话测试。重复 source 后出现 PATH 重复、重复输出或函数冲突，说明初始化不幂等。

定位命令冲突

Get-Command <command-name> -All |
  Select-Object CommandType, Name, Source, Version

type -a <command-name>
command -V <command-name>

whence -a <command-name>

不要只看 --version；两个不同路径的程序可能报告相近版本，却使用不同插件、证书库或配置目录。

Windows Terminal 显示 PowerShell，实际仍是 5.1

窗口标题相似，某些 PowerShell 7 语法或模块不可用。

查看 $PSVersionTable.PSEdition、$PSVersionTable.PSVersion 与 $PSHOME。

Profile 的 commandline 仍指向 powershell.exe，或默认 Profile 没有切换。

把目标 Profile 明确指向 pwsh.exe，保留 5.1 供兼容模块使用。

关闭旧标签页，从新 Profile 启动并再次检查三个字段。

终端中能运行，IDE 或 CI 找不到命令

交互终端成功，IDE Task 或 CI 报 command not found。

比较会话类型、PATH、命令解析位置和启动文件。

命令只在 .bashrc、.zshrc 或个人 PowerShell Profile 中初始化；非交互进程没有读取。

把项目依赖放入项目脚本、wrapper 或显式环境配置，不依赖个人交互初始化。

从无 Profile/rc 的干净非交互进程执行项目脚本。

修改了启动文件，新会话没有生效

编辑 .bash_profile 却启动 non-login bash，或编辑 .zshrc 但进程不是 zsh。

检查实际进程、login/interactive 状态、$PROFILE 或 ZDOTDIR。

修改了错误文件，或 Terminal Profile 启动了另一个 Shell。

根据启动矩阵把配置放入正确文件，避免复制到所有 rc 文件。

新建会话并用唯一无秘密标记确认加载一次。

PATH 越来越长，同一命令出现多个版本

每次重载 Profile 后 PATH 重复，终端与 IDE 解析不同版本。

逐项输出 PATH，并使用 Get-Command -All、type -a 或 whence -a。

初始化脚本无条件追加路径，多个包管理器或版本管理器同时接管同一工具。

选择一个 owner，增加存在性与去重判断，删除过时入口。

连续重载两次后 PATH 不增长，所有入口解析一致。

zsh 补全出现不安全目录警告

compinit 中止或提示 insecure directories。

运行 compaudit，检查目录 owner 与组/其他用户写权限。

补全目录可被不可信用户修改，Shell 拒绝加载代码。

修正目标目录 owner 和最小写权限，清理来源不明补全文件。

重新运行 compinit，确认无警告且目标命令可补全。

PowerShell 脚本被执行策略阻止

脚本提示未签名或执行被禁用。

运行 Get-ExecutionPolicy -List，确认策略来源与作用域，并检查文件来源。

组织策略、下载标记、签名要求或作用域优先级生效。

按组织流程签名、解除可信文件的来源标记，或在允许的最小作用域调整；不使用机器级 Bypass。

新会话中执行目标脚本并重新查看策略列表，确认没有扩大边界。

终端启动文件会被每个会话加载，是最不适合保存秘密的位置之一。不要在 $PROFILE、.bashrc、.zshrc、Windows Terminal settings.json 中写真实 Token、密码、云 AK/SK、私钥内容或带凭证代理 URL。Profile 可以调用组织批准的凭证注入工具，但不应输出秘密，也不应把秘密复制到长期环境变量。

代理配置具有分层边界：Terminal 宿主、Shell 环境、Git、包管理器、JDK 与容器可能读取不同来源。终端里 HTTPS_PROXY 生效，不代表 IDE、Windows 服务或 CI 生效。这里的关键动作是识别每层配置来源，并把网络、代理和证书问题交给对应诊断链路继续取证。

权限要求：

Windows Terminal Profile 默认 elevate: false。日常 Shell 不以 Administrator/root 启动。Profile 和补全目录只能由当前用户或受信管理员修改。

不通过全局执行策略 Bypass、sudo 启动整个开发流程或忽略 compinit 安全检查解决问题。共享终端配置不得包含个人用户名、本机绝对路径、企业内网域名和真实凭证。

团队终端基线应约束行为，不统一个人审美。至少维护：

治理对象	团队约定
支持 Shell	名称、主要版本通道、适用平台、兼容例外
项目入口	可直接执行的仓库脚本或任务，不依赖个人别名
PATH owner	每类运行时由哪个版本管理器或安装源负责
Profile	最小、幂等、无秘密、有备份和回退方式
补全	来源、加载位置、权限检查、升级 owner
执行策略	企业签名要求、例外审批和最小作用域
验收	新会话、IDE、非交互脚本与 CI 的一致性证据

项目模板可以提供 doctor.ps1 和 doctor.sh，但不得自动修改用户 Profile。诊断与修复分开：先输出当前状态和建议，用户确认后再执行范围明确的安装或配置动作。

升级 PowerShell、Terminal、Shell 框架或补全前，先在代表性项目验证启动时间、命令解析、IDE 集成和脚本兼容。Profile 应纳入个人受控备份；团队共享片段必须版本化、评审并提供回退版本。

会话类型决定配置是否存在

“我的 PATH 已经配置”只对某种启动链成立。终端标签页、IDE、任务运行器、远程命令和 CI 可能分别启动 login、interactive 或 non-interactive Shell。排障时先记录宿主、启动命令、进程参数、会话类型和实际读取文件，再比较 PATH；不要从一个交互窗口的结果推导所有环境。

架构取舍是把项目必要条件放进仓库，把个人体验留在 Profile。项目脚本越依赖个人 rc 文件，换机、CI 和新人接入成本越高。

Profile 是代码执行边界

Profile、补全和主题都会执行代码，并继承当前用户权限与环境。第三方安装脚本若直接修改 rc 文件，团队必须审查它写入了什么、从哪里下载、何时联网以及如何卸载。发现 Profile 被污染时，先用无 Profile/rc 模式启动干净 Shell，比较命令解析，再逐段恢复。

PowerShell 可使用 pwsh -NoProfile，bash 可使用受控的 --noprofile --norc 诊断方式，zsh 可在隔离环境中禁用 rc 读取。它们用于定位，不应成为长期绕过配置治理的默认启动方式。

PATH 冲突是所有权问题

同一工具同时由系统包管理器、语言版本管理器、IDE 和手工压缩包提供时，调整顺序只能暂时掩盖冲突。团队应决定谁拥有版本选择、谁负责升级、项目如何声明版本、缓存如何隔离。判断标准是新会话、IDE 与 CI 对同一项目解析到同一契约版本，而不是个人终端“碰巧先找到正确的”。

管理员终端会放大所有失误

把 Profile 默认设为管理员运行，会让普通构建脚本、第三方补全和误输入命令都获得高权限，也会在工作区制造高权限 owner。需要安装系统组件时单独打开短生命周期提权会话，操作完成立即关闭；项目构建必须回到普通用户重跑并清理。

配置升级必须可回退

Shell 框架、主题和补全升级可能改变启动顺序、函数名称和性能。变更前记录启动耗时、关键命令路径和配置版本；变更后验证新会话、IDE 与非交互脚本。出现问题时回退到已知配置，而不是在多个 rc 文件继续叠补丁。长期无人维护的共享 Profile 片段应下线，不应永久注入所有开发机。

已分清 Terminal、Terminal Profile、Shell 与 Shell 启动文件。当前宿主的启动命令和实际 Shell 进程一致。PowerShell 5.1 与 PowerShell 7 的路径、版本和用途已区分。

bash/zsh 的 login 与 interactive 状态经过实测。实际 $PROFILE、Bash 启动文件或 ZDOTDIR 路径已确认。PATH 没有重复追加，同一工具只有一个明确 owner。

关键命令在新会话、IDE 与项目脚本中解析到预期位置。Bash/zsh 补全已加载，目录 owner 与写权限安全。Windows Terminal Profile 默认不提权，不写死自动生成 GUID。

PowerShell 执行策略没有使用机器级 Bypass 作为通用修复。Profile/rc 文件轻量、幂等、无联网副作用、无真实凭证。项目入口由仓库脚本或任务承载，不依赖个人别名。

CI 和非交互脚本不依赖个人 .bashrc、.zshrc 或 $PROFILE。动态版本、默认 Shell 和安装入口按执行时的官方资料复核。已完成临时标记加载、新会话验证和清理闭环。