环境变量与 PATH 完全指南从命令查找到 API 密钥安全的实战手册【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe导读每次你在终端输入git或python系统都要去找这个程序在哪里每次你的代码调用大模型 API程序要知道用哪个密钥。这两件事背后都是同一套机制——环境变量。本指南以 easy-vibevibe coding 101面向 AI 原生产品构建者的入门课程的开发环境为背景系统讲解 PATH 查找机制、export 作用域、.env密钥管理与生产环境注入方案读完你就能独立排查command not found、多版本冲突和变量设置了却读不到三大高频问题。0. 每个程序身边都带着一组配置运行中的每个程序都持有一组「键值」配置叫做环境变量。程序可以随时读取这些配置用来了解当前的运行环境当前用户是谁USER、主目录在哪HOME、系统是什么OS、该去哪里找命令PATH……环境变量的两大用途贯穿整个 AI 开发工作流系统层面定位可执行文件PATH、解析依赖路径应用层面向程序注入运行时配置尤其是大模型 API 的密钥如 OpenAI、Anthropic、DeepSeek 的 API Key。在这套课程配套的文档站仓库中部署链路本身也依赖环境变量的继承机制构建阶段node:20-alpine镜像里的 Node.js 运行时、运行阶段nginx:alpine镜像里 Nginx 进程读取的配置都是各自进程环境变量与文件系统的组合见 Dockerfile。理解环境变量就是理解程序如何感知它所在的世界。1. PATH命令查找机制PATH是一个特殊的环境变量存着一串目录路径用冒号:分隔。你输入git时Shell 就按这串目录的顺序一个一个地进去找名叫git的可执行文件——找到第一个就立刻停止。$ echo $PATH /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin三个关键规律目录在 PATH 里越靠前优先级越高找到第一个就停止不会继续搜索所有目录都没有 →command not found。这个顺序即优先级的机制解释了你在本课程 Stage 2/Stage 3 中会反复遇到的真实问题为什么python指向系统旧版而不是你刚装的 3.12为什么node不是你用 nvm 装的那个——答案都在 PATH 的目录顺序里。2. 安装工具后要重启终端的必要性安装 nvm、Homebrew、conda 这类工具时安装脚本会自动在~/.zshrc里追加一行把自己的目录加入 PATH# 安装脚本自动写入的内容示例 export PATH/usr/local/opt/python3.12/bin:$PATH这行代码只在新 Shell 启动时才执行。已经打开的终端窗口不受影响所以# 不重启也能立刻生效 source ~/.zshrc注意$PATH在追加时必须放在右侧并带上原有的值...:$PATH否则会覆盖掉系统原有的全部路径导致ls、cat这类基础命令都找不到。AI 开发工具常见情况# Ollama / pipx 装完报 command not found which ollama # 查实际安装位置 # pip 安装的 CLI 工具路径加入 PATH # macOS~/Library/Python/3.x/bin # Linux~/.local/bin export PATH$PATH:$HOME/.local/bin # 推荐用 pipx 安装命令行工具自动管理 PATH pipx install aider-chat这与课程 Stage 2 后端章节中部署云服务器、调用 AI 接口的流程直接相关当你通过 SSH 登录服务器安装运行环境后若提示command not found第一反应就应该是which定位 PATH 补齐而不是重装。3. 变量的作用域谁能看见这个变量环境变量不是广播给所有程序的——每个进程持有自己的一份副本从父进程继承而来修改自己的副本不会影响父进程。典型的继承链条用户级~/.zshrc 或 ~/.bashrc ↓ export 登录 Shell 进程 ↓ 继承 你启动的终端进程如 iTerm / VS Code 集成终端 ↓ 继承 终端里运行的每条命令node / python / git ... ↓ 继承 命令启动的子进程你的后端服务 → 大模型 API 调用三个关键结论只能向下继承子进程启动时从父进程拍照拿到一份副本副本彼此独立在某个终端里export一个变量其它已打开的终端窗口看不到修改不回溯子进程里改值不会传回父进程。这解释了本仓库部署文档DEPLOYMENT.md中反复强调配置要进环境的原因——只有把配置提升到运行环境层才能被正确继承给真正干活的进程。4. export决定子进程能不能读到这个变量设置变量时加不加export是完全不同的两件事# 只对当前 Shell 有效子进程读不到 MY_VARvalue # 标记为可继承子进程启动时自动获得副本 export MY_VARvalue要让变量跨会话永久存在把export写入配置文件# macOS (zsh) echo export MY_VARvalue ~/.zshrc source ~/.zshrc # 立刻生效不用重开终端 # Linux (bash) echo export MY_VARvalue ~/.bashrc source ~/.bashrc排错提示当程序明明设置了变量却读不到时90% 的情况是——变量确实在但没加export子进程根本看不到。5. API 密钥绝对不能写进代码调用 OpenAI、Anthropic、DeepSeek 等 API 时密钥就是你的「身份证 信用卡」。泄露了别人可以用你的额度消费费用由你承担。最常见的错误是把密钥直接写在代码里// ❌ 绝对禁止硬编码密钥 const apiKey sk-xxxxxxxxxxxxxxxxxxxx为什么必须避免硬编码风险说明代码提交即泄露一旦推送到 Git 仓库尤其是公开仓库密钥就永久暴露在历史记录里无法轮换改密钥要改代码、重新构建、重新发布环境不分离开发/测试/生产环境无法使用不同密钥被 Secret Scanner 自动发现GitHub 等平台会自动扫描泄露的密钥并通知厂商吊销等于强制失效从本课程的实战路径看你在 Stage 1 首次调用大模型 API、Stage 2 做后端集成时就会接触到这一原则——密钥管理的核心不是藏得好而是从一开始就不进代码。6. 本地开发用 .env 文件管密钥本地开发时把密钥放在项目根目录的.env文件里代码通过 dotenv 库读取。.env必须加入.gitignore不能提交到 Git。Python 读取方式pip install python-dotenv# 项目根目录的 .env 文件 # OPENAI_API_KEYsk-xxxxxxxxxxxxxxxxxxxx # DEEPSEEK_API_KEYsk-yyyyyyyyyyyyyyyyyyyy from dotenv import load_dotenv import os load_dotenv() # 读取项目根目录的 .env api_key os.getenv(OPENAI_API_KEY)Node.js 读取方式npm install dotenv// 项目根目录的 .env 文件 // OPENAI_API_KEYsk-xxxxxxxxxxxxxxxxxxxx require(dotenv).config() // 读取项目根目录的 .env const apiKey process.env.OPENAI_API_KEY配套最佳实践# .gitignore 中必须包含 .env # 提交一份变量名完整、值留空的模板 echo OPENAI_API_KEY .env.example # .env.example 可以安全提交到 Git这套.env.gitignore.env.example的组合是本课程所有涉及 AI 接口调用的项目如 Stage 1 的 AI 集成、Stage 2 的后端开发的标准密钥管理方式。7. 生产环境让运行平台注入密钥.env是开发阶段的便利工具。服务器和云平台上应该由运行环境负责注入密钥代码本身完全不感知密钥放在哪里云平台 / 容器平台在平台控制台的环境变量或Secrets配置项中注入平台会在进程启动时注入到环境中如 Vercel、ModelScope 等平台均支持此模式。本仓库配套的部署配置ms_deploy.json与 DEPLOYMENT.md 中描述的即是镜像构建 平台托管的思路密钥不会打进镜像而是由运行平台在容器启动时注入。systemd 服务自建服务器# /etc/systemd/system/my-app.service [Service] EnvironmentFile/etc/my-app.env ExecStart/usr/local/bin/my-app# /etc/my-app.env注意权限 OPENAI_API_KEYsk-xxxxxxxxsudo chmod 600 /etc/my-app.env # 仅所有者可读写 sudo systemctl daemon-reload sudo systemctl restart my-app核心原则生产环境中代码只读取process.env.XXX或对应语言的os.environ至于密钥是平台控制台配的、容器编排注入的还是 systemd 读的——代码一概不管。这样密钥不进镜像、不进代码仓库、可独立轮换才是安全的终极形态。8. 实战排错command not found# 第一步确认是否在 PATH 里 which python3 # 有输出说明找到了 # 第二步找到程序实际位置macOS brew list python | grep bin # 第三步把目录加入 PATH export PATH/找到的路径:$PATH source ~/.zshrc # 写入配置文件后记得 source装了两个版本用的不是我想要的which python # /usr/bin/python ← 系统旧版在 PATH 靠前 # 把新版目录放到 PATH 最前面 export PATH/usr/local/bin:$PATH which python # /usr/local/bin/python ← 新版现在优先了变量明明设置了程序却读不到原因解决忘了export加上export再试改了~/.zshrc没生效source ~/.zshrc用了.env但没装 dotenvpip install python-dotenv/npm install dotenv服务器上只在 SSH 会话有效改用 systemdEnvironmentFile名词速查术语含义PATH存储 Shell 搜索可执行文件的目录列表冒号分隔顺序决定优先级export将变量标记为可继承子进程启动时自动获得副本source在当前 Shell 重新执行配置文件使修改立即生效which显示某命令对应的可执行文件路径PATH 搜索的结果.env项目本地配置文件存开发用密钥必须加入.gitignore.env.example变量名完整、值留空的模板可以安全提交到 Gitchmod 600文件权限只有所有者可读写适合保护密钥文件Secret ScannerGitHub 等平台自动扫描密钥泄露发现后通知厂商吊销记住这条主线PATH 决定命令从哪来export 决定变量传给谁.env管好开发密钥平台注入管好生产密钥。掌握这四件事你的 AI 开发环境就再也不会被找不到命令和密钥泄露绊倒。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考