EnvManager

EnvManager 是一款原生 macOS 应用,用来集中浏览和编辑多个项目及其 Git worktree 中的 .env 文件。

它会按「项目 → Worktree → 环境文件」组织本地配置,提供 .env 语法高亮、行号、实时保存和磁盘冲突处理,同时避免把环境变量内容复制到应用自己的持久化数据中。

功能

  • 自动发现主仓库和通过 git worktree 注册的 worktree
  • 扫描 .env 与 .env.* 文件,包括 .env.local、.env.example 等
  • 支持普通文件夹;不是 Git 仓库时仍可作为单项目使用
  • 可折叠、可调整宽度的项目侧边栏
  • 基于 CodeEditTextView 的原生编辑体验
  • .env 语法高亮与行号
  • 输入后实时自动保存,并显示 Ready、Saving、Saved 等状态
  • 检测外部修改、写入失败和文件丢失,保留当前编辑缓冲区
  • 提供 Reload、Keep Mine、Retry 和 Save Copy 等恢复操作
  • 可分别设置浅色与深色主题
  • 可调整编辑器字体、字号、行高,并显示或隐藏空格字符
  • 关闭最后一个窗口时保持应用运行;点击 Dock 图标可重新打开主窗口

系统要求

  • macOS 14 Sonoma 或更高版本
  • Swift 6 工具链(推荐使用最新版 Xcode)
  • Git,用于发现已注册的 worktree

快速开始

克隆仓库并运行:

git clone https://github.com/passion729/EnvManager.git
cd EnvManager
./script/build_and_run.sh

脚本会通过 SwiftPM 构建应用,在 dist/EnvManager.app 生成本地 App Bundle,然后启动它。首次构建时 SwiftPM 会下载依赖。

也可以只构建或运行测试:

swift build
swift test

使用方法

  1. 点击侧边栏中的添加项目按钮,或按 ⌘O 选择一个项目目录。
  2. 等待项目节点上的加载指示结束。EnvManager 会读取 Git worktree 并扫描其中的环境文件。
  3. 在侧边栏展开项目和 worktree,然后选择需要编辑的 .env 文件。
  4. 直接编辑内容。每次已提交的文本变更都会按顺序实时写回磁盘。
  5. 通过编辑器底部状态栏确认保存状态。

常用快捷键:

快捷键操作
⌘O添加项目
⌘B展开或折叠侧边栏
⌘,打开设置

移除项目只会删除 EnvManager 保存的项目记录,不会删除项目目录、worktree 或任何 .env 文件。

实时保存与冲突处理

EnvManager 不区分查看模式和编辑模式。文件可写且没有未解决的错误时,编辑器会直接接受输入并实时保存。

每次有效的输入、粘贴、剪切、撤销或重做都会形成有序写入。写入使用同目录临时文件和原子替换,并保留支持的文件权限与文本特征。只有最新变更已经写入磁盘时,状态栏才会显示 Saved。

如果文件被其他程序修改,EnvManager 会暂停后续写入并保留内存中的编辑内容:

  • Reload:重新加载磁盘版本
  • Keep Mine:确认使用当前编辑内容覆盖已识别的磁盘版本
  • Retry:在写入失败后重试
  • Save Copy…:将当前内容另存为新文件

文件发现与安全边界

EnvManager 会扫描名称为 .env 或以 .env. 开头的普通文件,并跳过常见的依赖、缓存和构建目录,例如:

.git  .build  build  dist  node_modules  vendor  Pods  DerivedData  .cache

当前编辑范围为不超过 2 MiB 的 UTF-8 文件。应用拒绝编辑符号链接和具有多个硬链接的文件,并在读写时检查文件仍位于对应 worktree 中。

应用只持久化项目路径、侧边栏展开状态和当前选择等非敏感元数据。.env 内容、未保存缓冲区和变量值不会写入 EnvManager 自己的状态文件或诊断日志。源文件仍受 macOS 文件系统、备份和索引策略影响。

设置

从菜单栏选择 EnvManager → Settings…:

  • Appearance:分别选择浅色和深色主题
  • Editor:设置等宽字体、字号、行高和空格字符显示

主题和编辑器设置会立即应用到已打开的文件。设置窗口会保持在 EnvManager 主窗口上方。

项目结构

Sources/EnvManager/
├── App/                 # App 生命周期与组合入口
├── Domain/              # Project、Worktree、EnvironmentFile 与编辑状态
├── Features/            # 项目、侧边栏和编辑器功能
├── Filesystem/          # 扫描、读取、监听与原子写入
├── Git/                 # git worktree 发现
├── Persistence/         # 非敏感项目和导航状态
├── Settings/            # 主题与编辑器设置
├── UI/                  # SwiftUI/AppKit 编辑器桥接与 Muxy 风格组件
└── Resources/           # 内置主题资源

Tests/EnvManagerTests/   # Swift Testing 测试
script/                  # 本地构建与启动
scripts/                 # Release 构建与验证

项目使用 Swift Package Manager 管理,主依赖固定为 CodeEditTextView 0.12.1。

Release 构建

创建本地 ad-hoc 签名的 Release App:

./scripts/build-release.sh
./scripts/verify-release.sh

Developer ID 签名和公证流程参见 Docs/release.md。仓库不会保存签名证书、Apple 凭据或公证配置。

致谢

  • Muxy:界面风格、侧边栏交互与主题体验参考
  • CodeEditTextView:原生文本编辑器组件
  • Ghostty:内置终端主题格式与主题资源生态