diff --git a/README.md b/README.md
index 3205b07..55f6f87 100644
--- a/README.md
+++ b/README.md
@@ -50,9 +50,9 @@ macOS：
 - macOS 10.15+（Apple Silicon / Intel 均可）
 - 微信 4.x（macOS 版）
 - Xcode Command Line Tools：`xcode-select --install`
-- 需要对 `/Applications/WeChat.app` 做 ad-hoc 重签名（允许进程内存读取）
+- 需要对 `/Applications/WeChat.app` 做 ad-hoc 重签名（允许进程内存读取），重签名前须先退出微信
 - 需要 root 权限运行扫描器
-- `db_dir` 默认类似 `~/Library/Containers/com.tencent.xinWeChat/Data/Library/Application Support/com.tencent.xinWeChat/2.0b4.0.9/<hash>/Message`
+- `db_dir` 默认类似 `~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage`
 
 ### 安装依赖
 
@@ -60,7 +60,35 @@ macOS：
 pip install -r requirements.txt
 ```
 
-Windows 如果遇到权限不足或全局环境不可写，可以改用：
+<details>
+<summary>⚠️ 安装失败？点击展开常见问题</summary>
+
+**问题：`error: externally-managed-environment` (PEP 668)**
+
+Homebrew Python (3.12+) 和部分 Linux 发行版禁止 `pip install` 直接写入系统 Python 环境，会报此错误。
+
+**解决：使用虚拟环境**
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate   # 激活虚拟环境
+pip install -r requirements.txt
+
+# 后续运行脚本时使用 .venv 中的 Python
+.venv/bin/python3 main.py
+.venv/bin/python3 decrypt_db.py
+```
+
+或使用 Makefile（已配置 `.venv/bin/python3`）：
+
+```bash
+make decrypt  # 等价于 .venv/bin/python3 main.py decrypt
+make web      # 等价于 .venv/bin/python3 main.py
+```
+
+---
+
+**Windows 权限不足或全局环境不可写**，可以改用：
 
 ```bash
 py -m pip install --user -r requirements.txt
@@ -68,6 +96,8 @@ py -m pip install --user -r requirements.txt
 
 如果需要读取受保护的进程或把依赖安装到系统 Python，也可能需要以管理员身份打开终端。
 
+</details>
+
 ### 快速开始
 
 Windows：
@@ -86,10 +116,11 @@ python3 main.py decrypt
 macOS（密钥扫描用 C 版本，见下文 [macOS 数据库密钥扫描](#macos-数据库密钥扫描-wechat-4x) 章节）：
 
 ```bash
-# 1. 重新签名（首次及微信升级后各一次）
+# 1. 退出微信，重新签名（首次及微信升级后各一次）
+killall WeChat
 sudo codesign --force --deep --sign - /Applications/WeChat.app
 
-# 2. 编译并运行扫描器
+# 2. 重新打开微信并登录，然后编译并运行扫描器
 cc -O2 -o find_all_keys_macos find_all_keys_macos.c -framework Foundation
 sudo ./find_all_keys_macos
 
@@ -124,14 +155,14 @@ macOS 版 `config.json` 示例：
 
 ```json
 {
-    "db_dir": "/Users/yourname/Library/Containers/com.tencent.xinWeChat/Data/Library/Application Support/com.tencent.xinWeChat/2.0b4.0.9/<hash>/Message",
+    "db_dir": "/Users/yourname/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/your_wxid/db_storage",
     "keys_file": "all_keys.json",
     "decrypted_dir": "decrypted",
     "wechat_process": "WeChat"
 }
 ```
 
-`db_dir` 路径：Windows 可在微信设置 → 文件管理中找到；Linux 默认在 `~/Documents/xwechat_files/<wxid>/db_storage`；macOS 在 `~/Library/Containers/com.tencent.xinWeChat/.../Message`（`<hash>` 是微信随机生成的账号目录）。
+`db_dir` 路径：Windows 可在微信设置 → 文件管理中找到；Linux 默认在 `~/Documents/xwechat_files/<wxid>/db_storage`；macOS 在 `~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage`（程序已支持自动检测）。
 
 ### Web UI 说明
 
@@ -350,6 +381,54 @@ sudo ./find_all_keys_macos <pid>
 python3 decrypt_db.py
 ```
 
+### 常见问题
+
+#### `task_for_pid failed: 5`
+
+以 root 运行扫描器后仍报此错，说明微信进程的 Hardened Runtime 签名未移除。
+
+**原因**：macOS 会阻止对带有 Hardened Runtime 标志的进程进行内存读取，即使以 root 身份运行也不行。微信默认签名包含此标志。
+
+**排查步骤**：
+
+```bash
+# 1. 检查微信当前签名（如包含 flags=0x10000(runtime) 则需要重签名）
+codesign -dvvv /Applications/WeChat.app 2>&1 | grep flags
+
+# 2. 必须先退出微信再重签名（微信在运行时重签名不会生效）
+killall WeChat
+sudo codesign --force --deep --sign - /Applications/WeChat.app
+
+# 3. 验证签名已变更（应显示 flags=0x2，不再有 runtime 标志）
+codesign -dvvv /Applications/WeChat.app 2>&1 | grep flags
+
+# 4. 重新打开微信并登录，然后运行扫描器
+sudo ./find_all_keys_macos
+```
+
+**注意**：
+- 微信每次更新后签名会恢复原始状态，需重新执行上述步骤
+- `--deep` 参数确保签名覆盖 App Bundle 内所有嵌套二进制文件
+- 重签名后必须重启微信，否则进程仍使用旧的签名凭证
+
+#### 未能自动检测微信数据目录
+
+程序已支持 macOS 自动检测微信数据目录。如果检测失败，手动查找并配置：
+
+```bash
+# 搜索 db_storage 目录
+find ~/Library/Containers/com.tencent.xinWeChat -type d -name "db_storage" 2>/dev/null
+```
+
+如有多个账号（多个 `db_storage` 目录），按修改时间判断当前活跃账号：
+
+```bash
+stat -f "%m %N" /path/to/account1/db_storage /path/to/account2/db_storage
+# 数值更大 = 最近活跃
+```
+
+然后编辑 `config.json`，将找到的路径填入 `db_dir` 字段。
+
 ## 免责声明
 
 本工具仅用于学习和研究目的，用于解密**自己的**微信数据。请遵守相关法律法规，不要用于未经授权的数据访问。
diff --git a/config.py b/config.py
index 4089b50..ff59b7b 100644
--- a/config.py
+++ b/config.py
@@ -162,11 +162,47 @@ def _auto_detect_db_dir_linux():
     return _choose_candidate(candidates)
 
 
+def _auto_detect_db_dir_macos():
+    """自动检测 macOS 微信 db_storage 路径。
+
+    微信 4.x 数据目录位于 ~/Library/Containers/com.tencent.xinWeChat/.../xwechat_files/<wxid>/db_storage，
+    路径中包含随机 hash，需要搜索定位。
+    """
+    base = os.path.expanduser(
+        "~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files"
+    )
+    if not os.path.isdir(base):
+        return None
+
+    seen = set()
+    candidates = []
+    pattern = os.path.join(base, "*", "db_storage")
+    for match in glob.glob(pattern):
+        normalized = os.path.normcase(os.path.normpath(match))
+        if os.path.isdir(match) and normalized not in seen:
+            seen.add(normalized)
+            candidates.append(match)
+
+    # 优先使用最近活跃账号：按 message 目录 mtime 降序
+    def _mtime(path):
+        msg_dir = os.path.join(path, "message")
+        target = msg_dir if os.path.isdir(msg_dir) else path
+        try:
+            return os.path.getmtime(target)
+        except OSError:
+            return 0
+
+    candidates.sort(key=_mtime, reverse=True)
+    return _choose_candidate(candidates)
+
+
 def auto_detect_db_dir():
     if _SYSTEM == "windows":
         return _auto_detect_db_dir_windows()
     if _SYSTEM == "linux":
         return _auto_detect_db_dir_linux()
+    if _SYSTEM == "darwin":
+        return _auto_detect_db_dir_macos()
     return None
 
 
@@ -197,6 +233,8 @@ def load_config():
             print(f"    请手动编辑 {CONFIG_FILE} 中的 db_dir 字段")
             if _SYSTEM == "linux":
                 print("    Linux 默认路径类似: ~/Documents/xwechat_files/<wxid>/db_storage")
+            elif _SYSTEM == "darwin":
+                print("    macOS 默认路径类似: ~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage")
             else:
                 print(f"    路径可在 微信设置 → 文件管理 中找到")
             sys.exit(1)
diff --git a/docs/bugfix/mac-deploy-issues.md b/docs/bugfix/mac-deploy-issues.md
new file mode 100644
index 0000000..17cb896
--- /dev/null
+++ b/docs/bugfix/mac-deploy-issues.md
@@ -0,0 +1,259 @@
+# macOS 部署问题记录
+
+> 环境：macOS (Apple Silicon / Intel), 微信 4.x, Python 3.14 (Homebrew)
+> 日期：2026-05-12
+
+---
+
+## 问题 1: `task_for_pid failed: 5` — 微信进程内存读取被拒绝
+
+### 现象
+
+```bash
+sudo ./find_all_keys_macos
+# 输出:
+# WeChat PID: 12276
+# task_for_pid failed: 5
+# Make sure: (1) running as root, (2) WeChat is ad-hoc signed
+```
+
+以 root 运行扫描器，但仍无法读取微信进程内存。
+
+### 原因
+
+微信 App 使用了 Apple **Hardened Runtime**（`flags=0x10000(runtime)`），即使以 root 身份运行，macOS 也会阻止对带有此标志的进程进行 `task_for_pid` 调用。
+
+验证方法：
+
+```bash
+codesign -dvvv /Applications/WeChat.app 2>&1 | grep flags
+# 输出: flags=0x10000(runtime)  ← 问题所在
+```
+
+### 修复
+
+1. **退出微信**（重签名需要进程不在运行）
+
+   ```bash
+   killall WeChat
+   ```
+
+2. **执行 ad-hoc 重签名**（移除 Hardened Runtime 标志）
+
+   ```bash
+   sudo codesign --force --deep --sign - /Applications/WeChat.app
+   ```
+
+3. **验证签名已变更**
+
+   ```bash
+   codesign -dvvv /Applications/WeChat.app 2>&1 | grep -E "flags|Authority"
+   # 正确输出应类似: flags=0x2
+   # 不应再出现 flags=0x10000(runtime) 或 Authority=Developer ID
+   ```
+
+4. **重新打开微信并登录**，再运行扫描器
+
+   ```bash
+   sudo ./find_all_keys_macos
+   ```
+
+### 注意事项
+
+- 微信**每次更新**后签名会恢复为原始状态，需重新执行上述步骤
+- `--deep` 参数确保签名覆盖 App Bundle 内所有嵌套二进制文件
+- 重签名后必须重启微信，否则进程仍使用旧的签名凭证
+
+---
+
+## 问题 2: 自动检测微信数据目录失败
+
+### 现象
+
+```bash
+.venv/bin/python3 decrypt_db.py
+# 输出:
+# [!] 未能自动检测微信数据目录
+#     请手动编辑 config.json 中的 db_dir 字段
+```
+
+或
+
+```bash
+.venv/bin/python3 main.py
+# 输出:
+# [!] 未能自动检测微信数据目录
+```
+
+### 原因
+
+`config.py` 中的 `auto_detect_db_dir()` 函数仅实现了 Windows 和 Linux 的自动检测逻辑，macOS 分支直接返回 `None`：
+
+```python
+def auto_detect_db_dir():
+    if _SYSTEM == "windows":
+        return _auto_detect_db_dir_windows()
+    if _SYSTEM == "linux":
+        return _auto_detect_db_dir_linux()
+    return None  # ← macOS 未实现
+```
+
+macOS 微信数据目录位于 `~/Library/Containers/com.tencent.xinWeChat/...`，路径中包含随机 hash，需要搜索才能定位。
+
+### 修复
+
+已在 `config.py` 中实现 macOS 自动检测，同时改进了检测失败时的提示信息。
+
+#### 代码改动
+
+1. **新增 `_auto_detect_db_dir_macos()` 函数**（`config.py`）
+
+   ```python
+   def _auto_detect_db_dir_macos():
+       """自动检测 macOS 微信 db_storage 路径。"""
+       base = os.path.expanduser(
+           "~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files"
+       )
+       if not os.path.isdir(base):
+           return None
+
+       seen = set()
+       candidates = []
+       pattern = os.path.join(base, "*", "db_storage")
+       for match in glob.glob(pattern):
+           normalized = os.path.normcase(os.path.normpath(match))
+           if os.path.isdir(match) and normalized not in seen:
+               seen.add(normalized)
+               candidates.append(match)
+
+       # 优先使用最近活跃账号：按 message 目录 mtime 降序
+       def _mtime(path):
+           msg_dir = os.path.join(path, "message")
+           target = msg_dir if os.path.isdir(msg_dir) else path
+           try:
+               return os.path.getmtime(target)
+           except OSError:
+               return 0
+
+       candidates.sort(key=_mtime, reverse=True)
+       return _choose_candidate(candidates)
+   ```
+
+2. **在 `auto_detect_db_dir()` 中接入 macOS 分支**
+
+   ```python
+   def auto_detect_db_dir():
+       if _SYSTEM == "windows":
+           return _auto_detect_db_dir_windows()
+       if _SYSTEM == "linux":
+           return _auto_detect_db_dir_linux()
+       if _SYSTEM == "darwin":
+           return _auto_detect_db_dir_macos()  # ← 新增
+       return None
+   ```
+
+3. **改进检测失败时的提示**：macOS 提示正确的默认路径格式
+
+   ```
+   [!] 未能自动检测微信数据目录
+       请手动编辑 config.json 中的 db_dir 字段
+       macOS 默认路径类似: ~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<wxid>/db_storage
+   ```
+
+#### 临时解决方案（如自动检测仍失败）
+
+手动查找并配置 `db_dir`：
+
+```bash
+find ~/Library/Containers/com.tencent.xinWeChat -type d -name "db_storage" 2>/dev/null
+```
+
+如有多个账号，按修改时间判断当前活跃账号：
+
+```bash
+stat -f "%m %N" /path/to/account1/db_storage /path/to/account2/db_storage
+```
+
+然后编辑 `config.json` 填入路径。
+
+---
+
+## 问题 3: Homebrew Python 拒绝全局 pip 安装
+
+### 现象
+
+```bash
+pip3 install -r requirements.txt
+# 报错: error: externally-managed-environment
+# 提示: PEP 668 — 不能直接向系统 Python 安装包
+```
+
+### 原因
+
+Homebrew 的 Python 3.14 遵循 [PEP 668](https://peps.python.org/pep-0668/)，禁止 `pip install` 直接写入系统 Python 环境，防止破坏包管理器的依赖关系。
+
+### 修复
+
+使用虚拟环境：
+
+```bash
+cd /Users/drulu/Documents/GitHub/wechat-decrypt
+
+# 创建虚拟环境
+python3 -m venv .venv
+
+# 激活并安装依赖
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 后续运行脚本时使用 .venv 中的 Python
+.venv/bin/python3 main.py
+.venv/bin/python3 decrypt_db.py
+```
+
+或使用 Makefile（已配置 `.venv/bin/python3`）：
+
+```bash
+make decrypt  # 等价于 .venv/bin/python3 main.py decrypt
+make web      # 等价于 .venv/bin/python3 main.py
+```
+
+---
+
+## 完整部署流程（macOS）
+
+将以上修复整合为正确的部署顺序：
+
+```bash
+# 1. 安装 Xcode CLI 工具
+xcode-select --install
+
+# 2. 创建虚拟环境并安装依赖
+cd ~/Documents/GitHub/wechat-decrypt
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 3. 退出微信 → 重签名 → 重启微信
+killall WeChat
+sudo codesign --force --deep --sign - /Applications/WeChat.app
+# 然后手动打开微信并登录
+
+# 4. 编译 C 扫描器
+cc -O2 -o find_all_keys_macos find_all_keys_macos.c -framework Foundation
+
+# 5. 提取密钥
+sudo ./find_all_keys_macos
+
+# 6. 启动 Web UI（db_dir 已自动检测，无需手动配置）
+.venv/bin/python3 main.py          # 启动 Web UI → http://localhost:5678
+.venv/bin/python3 decrypt_db.py    # 或仅全量解密
+```
+
+## 修复状态汇总
+
+| 问题 | 代码修复 | 说明 |
+|------|---------|------|
+| `task_for_pid failed: 5` | ❌ 无法代码修复 | 系统级限制，需手动重签名微信 |
+| 自动检测 `db_dir` 失败 | ✅ 已修复 | `config.py` 新增 `_auto_detect_db_dir_macos()`，自动搜索 `~/Library/Containers/` |
+| Homebrew Python 拒绝 pip 安装 | ❌ 无法代码修复 | 环境限制，需使用虚拟环境 |