docs: 完善 Homebrew 安装与配置说明，明确 .env 路径与运行方式

- 在 README 与入门指南中新增 Homebrew 安装步骤，并将“下载”表述调整为“安装”，同时保留二进制下载流程
- 区分 Homebrew 与直接下载两种配置方法，补充 --config 用法、环境变量示例及必填项说明
- 统一运行示例命令为 yewresin，减少不同安装方式下的命令歧义
- 在配置参考中新增配置文件位置与默认行为说明，并更新 TODO 记录 XDG 配置目录改进方向

避免 Homebrew 安装后因程序位于 bin 目录而无法同目录放置 .env 的配置困惑，提升包管理器与 cron 场景的可用性。

Author: YewFence

README.md

@@ -37,7 +37,15 @@ sudo apt update && sudo apt install kopia
 kopia repository connect rclone --remote-path="gdrive:backup"
 ```
 
-### 2. 下载 YewResin
+### 2. 安装 YewResin
+
+#### Homebrew（macOS/Linux）
+
+```bash
+brew install yewfence/tap/yewresin
+```
+
+#### 下载可执行文件
 
 根据系统架构下载对应的二进制文件：
 
@@ -62,39 +70,58 @@ chmod +x yewresin
 
 ### 3. 配置
 
-创建 `.env` 文件（与 yewresin 同目录）：
+#### Homebrew 安装
+
+Homebrew 安装后，程序位于 `bin/` 目录下，无法在同目录放置 `.env` 文件。推荐使用 `--config` 指定配置文件：
+
+```bash
+# 创建配置目录
+mkdir -p ~/.config/yewresin
+# 下载示例文件
+wget https://github.com/YewFence/YewResin/releases/latest/download/.env.example -O ~/.config/yewresin/.env
+# 编辑配置
+vim ~/.config/yewresin/.env
+
+# 运行时指定配置文件
+yewresin --config ~/.config/yewresin/.env
+```
+
+或者直接使用环境变量（适合 cron 场景）：
 
 ```bash
-# 在脚本所在目录下载示例文件
+BASE_DIR=/opt/docker_file EXPECTED_REMOTE=gdrive:backup yewresin -y
+```
+
+#### 直接下载安装
+
+在程序同目录创建 `.env` 文件：
+
+```bash
+cd ~/yewresin
 wget https://github.com/YewFence/YewResin/releases/latest/download/.env.example
 cp .env.example .env
 ```
 
-必要环境变量配置：
+#### 必要环境变量
+
 ```bash
 # Docker Compose 项目总目录
 BASE_DIR=/opt/docker_file
 # Kopia 远程路径
 EXPECTED_REMOTE=gdrive:backup
 ```
 
-或者直接临时设置环境变量运行：
-
-```bash
-BASE_DIR=/opt/docker_file EXPECTED_REMOTE=gdrive:backup ./yewresin
-```
-
 ### 4. 运行
 
 ```bash
 # 模拟运行（推荐先测试）
-./yewresin --dry-run
+yewresin --dry-run
 
 # 执行备份（需确认）
-./yewresin
+yewresin
 
 # 跳过确认直接执行（适用于 cron）
-./yewresin -y
+yewresin -y
 ```
 
 ## 文档

TODO.md

@@ -11,7 +11,7 @@
 ## 可选改进
 
 - [x] 单元测试
-- [ ] 更结构化的配置格式（YAML/TOML）
+- [ ] 支持 XDG 规范配置目录（如 `~/.config/yewresin/.env`），改善 Homebrew 等包管理器安装后的配置体验
 - [ ] JSON 日志格式输出选项
 - [ ] 引入 pinact github action 自动 pin action 版本
 

docs/guide/getting-started.md

@@ -23,7 +23,15 @@ sudo apt update && sudo apt install kopia
 kopia repository connect rclone --remote-path="gdrive:backup"
 ```
 
-## 2. 下载 YewResin
+## 2. 安装 YewResin
+
+### Homebrew（macOS/Linux）
+
+```bash
+brew install yewfence/tap/yewresin
+```
+
+### 下载可执行文件
 
 根据系统架构下载对应的二进制文件：
 
@@ -48,15 +56,39 @@ chmod +x yewresin
 
 ## 3. 配置
 
-创建 `.env` 文件（与 yewresin 同目录）：
+### Homebrew 安装 {#homebrew}
+
+Homebrew 安装后，程序位于 `bin/` 目录下，无法在同目录放置 `.env` 文件。推荐使用 `--config` 指定配置文件：
+
+```bash
+# 创建配置目录
+mkdir -p ~/.config/yewresin
+# 下载示例文件
+wget https://github.com/YewFence/YewResin/releases/latest/download/.env.example -O ~/.config/yewresin/.env
+# 编辑配置
+vim ~/.config/yewresin/.env
+
+# 运行时指定配置文件
+yewresin --config ~/.config/yewresin/.env
+```
+
+或者直接使用环境变量（适合 cron 场景）：
+
+```bash
+BASE_DIR=/opt/docker_file EXPECTED_REMOTE=gdrive:backup yewresin -y
+```
+
+### 直接下载安装
+
+在程序同目录创建 `.env` 文件：
 
 ```bash
-# 在脚本所在目录下载示例文件
+cd ~/yewresin
 wget https://github.com/YewFence/YewResin/releases/latest/download/.env.example
 cp .env.example .env
 ```
 
-必要环境变量配置：
+### 必要环境变量
 
 ```bash
 # Docker Compose 项目总目录
@@ -76,13 +108,13 @@ EXPECTED_REMOTE=gdrive:backup
 
 ```bash
 # 模拟运行（推荐先测试）
-./yewresin --dry-run
+yewresin --dry-run
 
 # 执行备份（需确认）
-./yewresin
+yewresin
 
 # 跳过确认直接执行（适用于 cron）
-./yewresin -y
+yewresin -y
 ```
 
 ## 5. 备份连接凭证

docs/reference/configuration.md

@@ -44,6 +44,13 @@
 
 如果必填项（如 `BASE_DIR` 和 `EXPECTED_REMOTE`）最终未设置，程序会直接报错并退出。部分可选项如果未设置会回退到内置默认值。
 
+## 配置文件位置
+
+- 直接下载安装：程序同目录的 `.env` 文件
+- `--config` 参数：手动指定任意路径的 `.env` 文件
+- Homebrew 安装后，程序位于 `bin/` 目录，无法在同目录放 `.env`，推荐使用 `--config` 指定（如 `~/.config/yewresin/.env`）
+- 如果默认路径下不存在 `.env` 文件，程序不会报错，但需要通过环境变量提供必填项
+
 ## 日志持久化说明
 
 - `LOG_FILE` 未配置时，日志只输出到标准输出，不会由程序写入任何日志文件