# redirect_hook

**Repository Path**: zhReimu/redirect_hook

## Basic Information

- **Project Name**: redirect_hook
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# redirect_hook

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

一个高性能的 Windows 文件路径与环境变量重定向库，基于 API Hook 技术实现透明的文件系统虚拟化。

## ✨ 特性

- 🎯 **透明重定向**：无需修改目标程序，自动重定向文件操作和环境变量
- 🔧 **双工作模式**：支持 DLL 注入和代理劫持两种使用方式
- 🚀 **高性能**：经过优化的 Hook 实现，最小化性能开销
- 🛡️ **稳定可靠**：内置崩溃诊断、重入保护和异常处理机制
- 📝 **灵活配置**：支持通配符、环境变量展开、相对路径
- 🏗️ **双架构支持**：提供 x86 和 x64 两个版本

## 🎮 使用场景

- 游戏存档重定向（如将存档从 AppData 重定向到便携目录）
- 应用程序沙箱化
- 多开隔离（每个实例使用独立的配置和数据目录）
- 便携化部署（将系统路径重定向到程序目录）
- 开发测试环境隔离

## 📦 两种工作模式

### 1. 注入模式（推荐用于开发和测试）

将 DLL 注入到目标进程：

```bash
# 基本注入
injector.exe <进程ID> <DLL完整路径>

# 启用诊断模式注入（用于调试）
injector.exe --diag <进程ID> <DLL完整路径>
```

**优点**：灵活，可随时注入/卸载  
**适用于**：开发调试、临时测试、实验性配置

### 2. 代理模式（推荐用于生产部署）

利用 DLL 搜索顺序劫持：

1. 将 `redirect_hook.dll` 重命名为以下之一：
   - `version.dll` - 适用于大多数程序
   - `winmm.dll` - 适用于多媒体应用
   - `winhttp.dll` - 适用于网络应用

2. 将重命名的 DLL 和 `redirect.conf` 放到目标程序目录

3. 启动程序，DLL 自动加载并初始化

**优点**：自动加载，无需注入器  
**适用于**：最终用户部署、便携化打包、长期运行

## 🛠️ 构建

### 环境要求

- **操作系统**：Windows 10/11
- **编译器**：MSVC (Visual C++ 2019 或更新版本)
- **构建工具**：xmake 3.0+

### 构建步骤

```bash
# 配置 x64 版本
xmake f -p windows -a x64 -m release --toolchain=msvc

# 构建
xmake

# 配置 x86 版本
xmake f -p windows -a x86 -m release --toolchain=msvc
xmake -r

# 清理构建产物
xmake clean

# 清理配置缓存
xmake c

# 生成代理导出文件（通常自动执行，也可手动运行）
xmake generate_proxy

# 打包发布版本（包含两个架构）
xmake package_release
```

**输出位置**：
- `build/windows/x64/release/redirect_hook.dll`
- `build/windows/x86/release/redirect_hook.dll`
- `build/windows/<arch>/release/{injector.exe, test_write.exe, redirect.conf}`
- `build/redirect_hook.zip`（发布包）

## ⚙️ 配置文件

配置文件 `redirect.conf` 使用 INI 格式，支持以下节：

### [GLOBAL] - 全局设置

```ini
[GLOBAL]
workdir, ./my_data
```

- `workdir`：后续相对路径的基准目录（相对于 DLL 所在目录）

### [LOGGER] - 日志配置

```ini
[LOGGER]
level, debug
path, ./logs/redirect_hook.log
```

- `level`：日志级别（`error` / `warn` / `info` / `debug`）
- `path`：日志文件路径（支持相对路径）

### [DIAGNOSTICS] - 诊断配置

```ini
[DIAGNOSTICS]
enabled, true
dump_dir, ./logs/dumps
```

- `enabled`：是否启用崩溃诊断（`true` / `false` / `1` / `0` / `yes` / `no`）
- `dump_dir`：minidump 输出目录
- 启用后，Hook 内部异常会记录调用栈、生成 `.dmp` 文件并自动回退到原始 API
- 游戏进程发生未处理异常时，会在 `ERROR` 日志中记录异常码、线程、符号化调用栈和最近 32 条文件操作，并生成独立的 `.dmp` 文件
- 诊断过滤器会链式调用进程原有的未处理异常过滤器，不会主动吞掉游戏异常

### [FILE] - 文件路径重定向

```ini
[FILE]
%APPDATA%, ./appdata
%LOCALAPPDATA%, ./localappdata
C:\ProgramData\MyApp, ./data
```

**规则**：`源路径, 目标路径`

- 支持环境变量（`%APPDATA%`、`%USERPROFILE%` 等）
- 支持绝对路径和相对路径
- 匹配前缀即重定向（如 `C:\Users\xxx\AppData\Roaming\MyApp\save.dat` 会被重定向）

### [ENV] - 环境变量重定向

```ini
[ENV]
%APPDATA%, ./appdata
```

**规则**：`环境变量名, 返回值`

- 拦截 `GetEnvironmentVariable` 调用并返回自定义值

### 完整示例

参考 [redirect.conf.example](./redirect.conf.example)

```ini
[GLOBAL]
workdir, ./portable_data

[LOGGER]
level, info
path, ./logs/redirect.log

[DIAGNOSTICS]
enabled, false
dump_dir, ./logs/dumps

[FILE]
%APPDATA%\MyGame, ./saves
%LOCALAPPDATA%\MyGame\Config, ./config

[ENV]
%APPDATA%, ./appdata
```

## 🧪 测试验证

### 1. 基本功能测试

```bash
# 构建 x64 版本
xmake f -a x64 && xmake

# 编辑配置文件
notepad build/windows/x64/release/redirect.conf

# 运行测试工具
build/windows/x64/release/test_write.exe
```

观察文件是否被重定向到目标位置。

### 2. 注入模式测试

```bash
# 启动目标程序，获取进程 ID
tasklist | findstr target.exe

# 注入 DLL
build/windows/x64/release/injector.exe <PID> <DLL绝对路径>

# 启用诊断模式注入（调试用）
build/windows/x64/release/injector.exe --diag <PID> <DLL绝对路径>
```

### 3. 代理模式测试

```bash
# 1. 将 redirect_hook.dll 复制到目标程序目录并重命名为 version.dll
copy build\windows\x64\release\redirect_hook.dll "C:\Program Files\MyApp\version.dll"

# 2. 复制配置文件
copy redirect.conf.example "C:\Program Files\MyApp\redirect.conf"

# 3. 编辑配置文件
notepad "C:\Program Files\MyApp\redirect.conf"

# 4. 启动目标程序
```

### 4. 检查日志

```bash
# 查看运行日志
type logs\redirect_hook.log

# 查看崩溃转储（如果启用了诊断）
dir logs\dumps\
```

## 📊 性能优化

本项目经过多项性能优化：

- ✅ **栈消耗优化**：单次 Hook 调用栈消耗从 ~48KB 降至 ~24KB
- ✅ **重入保护**：基于 TLS 的重入检测，避免双重 Hook 处理
- ✅ **智能缓存**：路径规范化结果缓存
- ✅ **最小化锁竞争**：使用 SRW 锁替代临界区
- ✅ **编译优化**：Release 构建启用 `/GL /LTCG /O1` 优化

## 🔧 技术细节

### 架构设计

```
┌─────────────────────────────────────────────┐
│           目标应用程序                        │
│  CreateFileW / GetEnvironmentVariable / ... │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│              Win32 API Hook                  │
│   (file_ops.c / env_ops.c / find_ops.c)     │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│            重入保护（TLS）                    │
│        避免 Win32 + NT 双重处理              │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│           NT API Hook (可选)                 │
│        (NtCreateFile / NtOpenFile)           │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│            重定向引擎                         │
│   (redirect_core.c / redirect_config.c)     │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│            原始 Windows API                   │
│     (fpCreateFileW / fpNtCreateFile)         │
└─────────────────────────────────────────────┘
```

### 核心组件

- **Hook 引擎**：基于 [MinHook](https://github.com/TsudaKageyu/minhook) 实现
- **重定向引擎**：规则匹配、路径规范化、环境变量展开
- **代理导出**：x86/x64 汇编跳转桩，实现透明转发
- **诊断系统**：SEH 异常处理 + minidump 生成

### 关键文件

| 文件 | 说明 |
|------|------|
| `src/redirect_dll.c` | DLL 入口点和初始化逻辑 |
| `src/redirect_core.c` | 重定向引擎核心 |
| `src/redirect_config.c` | 配置文件解析 |
| `src/hooks/file_create_ops.c` | 文件创建 Hook |
| `src/hooks/file_delete_ops.c` | 文件删除 Hook |
| `src/hooks/nt_ops.c` | NT API Hook |
| `src/hooks/hook_runtime.c` | Hook 运行时和重入保护 |
| `src/proxy.c` + `src/proxy_*.asm` | 代理导出实现 |
| `src/diagnostics_*.c` | 崩溃诊断和 minidump |

## 📂 项目结构

```
redirect_hook/
├── src/
│   ├── hooks/              # Hook 实现
│   │   ├── file_create_ops.c   # 文件创建 Hook
│   │   ├── file_delete_ops.c   # 文件删除 Hook
│   │   ├── file_attr_ops.c     # 文件属性 Hook
│   │   ├── file_move_ops.c     # 文件移动 Hook
│   │   ├── file_copy_ops.c     # 文件复制 Hook
│   │   ├── dir_ops.c           # 目录操作 Hook
│   │   ├── find_ops.c          # 文件查找 Hook
│   │   ├── nt_ops.c            # NT API Hook
│   │   ├── env_ops.c           # 环境变量 Hook
│   │   ├── hook_runtime.c      # Hook 运行时
│   │   └── hook_registry.c     # Hook 注册管理
│   ├── tools/              # 辅助工具
│   │   ├── injector.c      # DLL 注入工具
│   │   └── test_write.c    # 测试工具
│   ├── generated/          # 自动生成的代码（不入库）
│   ├── redirect_dll.c      # DLL 入口
│   ├── redirect_core.c     # 重定向核心
│   ├── redirect_config.c   # 配置解析
│   ├── redirect_state.c    # 状态管理
│   ├── path_utils.c        # 路径处理工具
│   ├── logger.c            # 日志系统
│   ├── diagnostics_*.c     # 诊断系统
│   ├── proxy.c             # 代理导出
│   └── proxy_*.asm         # 汇编跳转桩
├── include/                # 头文件
├── dll_resources/          # 资源和导出定义
│   ├── exports_version.def # version.dll 导出清单
│   ├── exports_winmm.def   # winmm.dll 导出清单
│   ├── exports_winhttp.def # winhttp.dll 导出清单
│   └── redirect_hook.rc    # 资源脚本
├── lib/
│   └── minhook-1.3.4/      # MinHook 库
├── build/                  # 构建输出（不入库）
├── xmake.lua               # xmake 构建脚本
├── redirect.conf.example   # 配置文件示例
├── CLAUDE.md               # 项目架构文档
├── FIXES_SUMMARY.md        # 修复记录
└── README.md               # 本文件
```

## 🐛 故障排查

### 问题：DLL 注入失败

**可能原因**：
- 目标进程架构不匹配（x86 程序需要 x86 DLL，x64 程序需要 x64 DLL）
- 权限不足（需要管理员权限）
- 目标进程有反注入保护

**解决方案**：
```bash
# 确认目标进程架构
tasklist /fi "imagename eq target.exe" /fo csv

# 以管理员身份运行注入器
# 或尝试代理模式
```

### 问题：重定向不生效

**排查步骤**：

1. 检查配置文件是否被正确加载：
```bash
# 启用 debug 日志
[LOGGER]
level, debug

# 查看日志
type logs\redirect_hook.log
```

2. 确认规则语法正确：
```ini
# 正确：使用逗号分隔
%APPDATA%, ./appdata

# 错误：使用等号
%APPDATA% = ./appdata
```

3. 检查路径匹配：
```bash
# 日志中会显示匹配的路径
[DEBUG] TryRedirectW: "C:\Users\xxx\AppData\Roaming\MyApp" -> "./appdata\MyApp"
```

### 问题：程序崩溃

**启用诊断模式**：

```ini
[DIAGNOSTICS]
enabled, true
dump_dir, ./logs/dumps
```

或使用 `--diag` 参数注入：
```bash
injector.exe --diag <PID> <DLL路径>
```

检查生成的 `.dmp` 文件和日志。

`redirect_hook.log` 中的 `stack[00]`、`stack[01]` 等记录是崩溃线程的调用栈；有可用符号时会显示函数名，否则显示模块名和偏移。诊断只负责在进程终止前留存信息，不会尝试让已经发生未处理异常的游戏继续运行。

### 问题：性能下降

**优化建议**：

1. 减少日志级别：
```ini
[LOGGER]
level, error  # 仅记录错误
```

2. 精简重定向规则（避免过多通配符）

3. 如果不需要 NT API Hook，可以在编译时禁用（修改 `hook_registry.c`）

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发前请阅读 [CLAUDE.md](CLAUDE.md) 了解项目架构。

## 📄 许可证

本项目采用 [MIT License](LICENSE) 授权。

## 🙏 致谢

- [MinHook](https://github.com/TsudaKageyu/minhook) - x86/x64 API Hook 库
- 所有贡献者和用户

## 📚 相关文档

- [CLAUDE.md](CLAUDE.md) - 项目架构和开发指南
- [FIXES_SUMMARY.md](FIXES_SUMMARY.md) - 性能优化和修复记录
- [redirect.conf.example](redirect.conf.example) - 配置文件示例

---

**最后更新**：2026-06-13  
**当前版本**：2.6.0