diff --git a/luac-path-analysis.md b/luac-path-analysis.md
new file mode 100644
index 00000000..d4542a81
--- /dev/null
+++ b/luac-path-analysis.md
@@ -0,0 +1,556 @@
+# Luac 路径处理机制分析
+
+## 概述
+
+本文档分析 Lua 编译器（luac）如何处理源文件路径，以及将绝对路径改为相对路径+运行时注入的影响。
+
+---
+
+## 1. 当前路径处理机制
+
+### 1.1 路径记录方式
+
+**关键代码位置：** `lauxlib.c:819`
+
+```c
+lua_pushfstring(L, "@%s", filename);  // 在文件名前添加 @ 前缀
+```
+
+- **格式规则**：文件名前加 `@` 前缀（如 `@/path/to/file.lua`）
+- **存储位置**：`Proto` 结构体中的 `TString *source` 字段 (`lobject.h:616`)
+- **生命周期**：编译时确定，保存到字节码，运行时只读
+
+### 1.2 路径使用场景
+
+| 使用场景 | 代码位置 | 说明 |
+|---------|---------|------|
+| 错误报告 | `ldebug.c:857` | 显示错误发生的文件和行号 |
+| 堆栈跟踪 | `ldebug.c:260-281` | 显示函数调用链中的源文件 |
+| 调试信息 | `ldebug.c:270` | 获取函数定义位置 |
+| 字节码保存 | `ldump.c:264` | 序列化 source 到二进制文件 |
+| 字节码加载 | `lundump.c:339` | 从字节码恢复 source 字段 |
+
+### 1.3 路径显示格式化
+
+**代码位置：** `lobject.c:682-717` - `luaO_chunkid()`
+
+```c
+void luaO_chunkid (char *out, const char *source, size_t srclen) {
+  if (*source == '=') {
+    // 字面量源：=stdin
+    memcpy(out, source + 1, srclen * sizeof(char));
+  }
+  else if (*source == '@') {
+    // 文件源：@/path/to/file.lua → 显示为 /path/to/file.lua
+    if (srclen <= bufflen)
+      memcpy(out, source + 1, srclen * sizeof(char));
+    else {
+      // 路径过长时添加 ... 前缀
+      addstr(out, RETS, LL(RETS));
+      memcpy(out, source + 1 + srclen - bufflen, bufflen * sizeof(char));
+    }
+  }
+  else {
+    // 字符串源：[string "code"]
+    // ...
+  }
+}
+```
+
+---
+
+## 2. 相对路径方案的影响分析
+
+### 2.1 优势
+
+#### ✅ 可移植性提升
+
+**场景示例：**
+```bash
+# 绝对路径字节码
+$ strings program.luac | grep "@"
+@/home/alice/project/src/main.lua
+@/home/alice/project/src/utils.lua
+
+# 迁移到其他机器后，路径失效
+# /home/alice/project 可能不存在
+
+# 相对路径字节码
+$ strings program.luac | grep "@"
+@src/main.lua
+@src/utils.lua
+
+# 只需设置基准路径
+export LUA_SOURCE_BASE=/opt/myapp
+```
+
+#### ✅ 安全性改善
+
+- **隐私保护**：不暴露开发者的用户名、项目结构
+- **信息安全**：防止逆向工程时获取完整目录结构
+
+**对比：**
+```
+绝对路径泄露信息：
+  @/home/alice/workspace/secret-project/核心算法/encryption.lua
+
+相对路径保护信息：
+  @src/encryption.lua
+```
+
+#### ✅ 字节码体积优化
+
+```
+绝对路径：@/home/user/very/long/path/to/project/src/modules/utils.lua (56 字节)
+相对路径：@src/modules/utils.lua (22 字节)
+
+大型项目（100+ 文件）可节省数 KB 字节码大小
+```
+
+### 2.2 劣势与挑战
+
+#### ⚠️ 调试体验下降
+
+**错误信息对比：**
+
+```lua
+-- 绝对路径（当前）
+/home/user/project/src/main.lua:42: attempt to index a nil value
+stack traceback:
+    /home/user/project/src/main.lua:42: in function 'foo'
+    /home/user/project/src/init.lua:10: in main chunk
+
+-- 相对路径（修改后）
+src/main.lua:42: attempt to index a nil value
+stack traceback:
+    src/main.lua:42: in function 'foo'
+    src/init.lua:10: in main chunk
+
+    ✗ 开发者无法直接定位文件完整路径
+    ✗ IDE 无法直接跳转（需要配置路径映射）
+```
+
+#### ⚠️ 路径解析复杂性
+
+**问题场景：**
+
+```bash
+# 场景1：工作目录影响
+$ cd /path/to/project
+$ lua src/main.luac          # 相对路径：src/main.lua ✓ 正确
+
+$ cd /tmp
+$ lua /path/to/project/src/main.luac  # 相对路径：src/main.lua ✗ 错误
+# 错误报告的 src/main.lua 会被解析为 /tmp/src/main.lua
+
+# 场景2：符号链接混淆
+$ ln -s /opt/myapp/v1.0 /opt/current
+$ /opt/current/bin/lua app.luac
+# 相对路径可能与实际文件系统结构不一致
+```
+
+**解决方案需求：**
+- 启动时记录基准路径
+- 错误报告时拼接完整路径
+- 处理符号链接、相对引用（`../`）
+
+#### ⚠️ 多模块路径歧义
+
+**冲突示例：**
+
+```
+project/
+├── frontend/
+│   └── utils.lua       # 模块A
+└── backend/
+    └── utils.lua       # 模块B
+
+# 两个模块编译后都记录为 @utils.lua
+# 错误报告时无法区分是哪个文件
+utils.lua:15: error  ← 是 frontend 还是 backend 的 utils.lua？
+```
+
+#### ⚠️ 调试器集成问题
+
+**影响工具：**
+- **VSCode Lua 插件**：无法直接打开 `src/main.lua`（不知道基准路径）
+- **ZeroBrane Studio**：需要手动配置项目根目录
+- **LuaJIT profiler**：热点分析时文件路径可能不准确
+
+**需要额外配置：**
+```json
+// VSCode settings.json
+{
+  "lua.workspace.library": {
+    "/path/to/project": true
+  }
+}
+```
+
+#### ⚠️ require 机制兼容性
+
+```lua
+-- package.path 使用绝对路径
+package.path = "/usr/local/share/lua/5.4/?.lua;./?.lua"
+
+-- 相对路径的 source 可能与 require 路径不匹配
+require("src.utils")
+-- 实际加载：./src/utils.lua
+-- source 记录：@src/utils.lua ✓ 一致
+
+require("utils")
+-- 实际加载：/usr/local/share/lua/5.4/utils.lua
+-- source 记录：@utils.lua ✗ 可能指向错误位置
+```
+
+---
+
+## 3. 实现方案设计
+
+### 3.1 方案A：编译时转换（推荐）
+
+**修改点：** `lauxlib.c:819`
+
+```c
+// 当前代码
+lua_pushfstring(L, "@%s", filename);
+
+// 修改为：计算相对路径
+static const char* make_relative_path(const char *filename) {
+  const char *base = getenv("LUAC_BASE_PATH");
+  if (base == NULL || *filename != '/')
+    return filename;  // 已经是相对路径或未设置基准路径
+
+  size_t base_len = strlen(base);
+  if (strncmp(filename, base, base_len) == 0 && filename[base_len] == '/')
+    return filename + base_len + 1;  // 跳过基准路径和分隔符
+
+  return filename;  // 不在基准路径下，保持原样
+}
+
+// 使用
+const char *rel_path = make_relative_path(filename);
+lua_pushfstring(L, "@%s", rel_path);
+```
+
+**使用方式：**
+```bash
+export LUAC_BASE_PATH=/home/user/project
+luac -o main.luac /home/user/project/src/main.lua
+# 字节码中记录为 @src/main.lua
+```
+
+### 3.2 方案B：运行时路径注入
+
+**修改点：** `ldebug.c:857` - 错误报告处
+
+```c
+// 在 luaG_runerror 中添加路径转换
+static const char* expand_source_path(const char *source) {
+  if (*source != '@')
+    return source;  // 非文件源
+
+  const char *rel_path = source + 1;  // 跳过 @
+  if (*rel_path == '/')
+    return source;  // 已经是绝对路径
+
+  // 拼接基准路径
+  static char full_path[1024];
+  const char *base = getenv("LUA_SOURCE_BASE");
+  if (base)
+    snprintf(full_path, sizeof(full_path), "@%s/%s", base, rel_path);
+  else
+    return source;  // 未设置基准路径，返回原样
+
+  return full_path;
+}
+
+// 修改错误报告
+const char *expanded = expand_source_path(ci_func(ci)->p->source);
+luaG_addinfo(L, msg, expanded, getcurrentline(ci));
+```
+
+**使用方式：**
+```bash
+export LUA_SOURCE_BASE=/home/user/project
+lua main.luac
+# 错误报告自动显示完整路径
+```
+
+### 3.3 方案C：混合方案（最佳实践）
+
+1. **编译时**：使用相对路径（方案A）
+2. **运行时**：提供路径扩展 API（方案B）
+3. **调试模式**：可选保留绝对路径
+
+```c
+// 添加编译选项
+#ifdef LUA_USE_RELATIVE_PATHS
+  const char *path = make_relative_path(filename);
+#else
+  const char *path = filename;
+#endif
+  lua_pushfstring(L, "@%s", path);
+```
+
+---
+
+## 4. 需要修改的代码位置
+
+### 4.1 核心修改点
+
+| 文件 | 行号 | 函数 | 修改内容 |
+|------|------|------|---------|
+| `lauxlib.c` | 819 | `luaL_loadfilex` | 添加相对路径转换逻辑 |
+| `ldebug.c` | 857 | `luaG_runerror` | 可选：添加路径扩展逻辑 |
+| `lobject.c` | 692 | `luaO_chunkid` | 可选：修改路径显示格式 |
+
+### 4.2 可能需要调整的位置
+
+| 文件 | 说明 |
+|------|------|
+| `lparser.c` | 检查编译器是否直接使用 source 字段 |
+| `ldump.c` | 确保字节码正确保存相对路径 |
+| `lundump.c` | 确保字节码加载时不做额外处理 |
+| `llex.c` | 检查词法分析器的路径使用 |
+
+---
+
+## 5. 测试方案
+
+### 5.1 功能测试
+
+```bash
+# 测试1：基本编译
+export LUAC_BASE_PATH=/home/user/project
+luac -o test.luac /home/user/project/src/test.lua
+strings test.luac | grep "@"
+# 预期输出：@src/test.lua
+
+# 测试2：错误报告
+lua test.luac
+# 预期输出：src/test.lua:X: error message
+
+# 测试3：运行时路径扩展
+export LUA_SOURCE_BASE=/home/user/project
+lua test.luac
+# 预期输出：/home/user/project/src/test.lua:X: error message
+```
+
+### 5.2 兼容性测试
+
+```lua
+-- test_error.lua
+function test_error()
+  error("测试错误")
+end
+
+function nested()
+  test_error()
+end
+
+nested()
+```
+
+**检查项：**
+- [ ] 错误信息显示正确的文件名
+- [ ] 堆栈跟踪包含完整调用链
+- [ ] `debug.getinfo()` 返回正确的 source
+- [ ] 字节码在不同目录下可正常运行
+
+### 5.3 性能测试
+
+```bash
+# 测试字节码大小
+ls -lh absolute_path.luac  # 绝对路径版本
+ls -lh relative_path.luac  # 相对路径版本
+
+# 测试运行时性能（路径扩展的开销）
+time lua -e 'for i=1,1000000 do pcall(error, "test") end'
+```
+
+---
+
+## 6. 推荐方案总结
+
+### 适合使用相对路径的场景
+
+- ✅ 分发的闭源应用程序
+- ✅ 容器化部署（Docker/Kubernetes）
+- ✅ 跨平台分发（Windows/Linux/macOS）
+- ✅ 安全性要求高的商业软件
+
+### 适合保留绝对路径的场景
+
+- ✅ 开发调试阶段
+- ✅ 内部工具（不分发）
+- ✅ 需要集成复杂 IDE 调试器
+- ✅ 多项目工作空间（避免路径冲突）
+
+### 最佳实践建议
+
+```makefile
+# Makefile 示例
+DEBUG ?= 0
+
+ifeq ($(DEBUG), 1)
+  # 开发模式：使用绝对路径
+  LUAC_FLAGS =
+else
+  # 发布模式：使用相对路径
+  export LUAC_BASE_PATH=$(CURDIR)
+  LUAC_FLAGS = -s  # strip debug info
+endif
+
+build:
+	luac $(LUAC_FLAGS) -o app.luac src/main.lua
+```
+
+---
+
+## 7. 潜在风险与缓解措施
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|---------|
+| 调试信息丢失 | 高 | 提供调试版本（绝对路径）和发布版本（相对路径） |
+| 路径解析失败 | 中 | 在错误报告中同时显示相对路径和基准路径 |
+| IDE 集成断裂 | 中 | 提供配置文档，说明如何设置路径映射 |
+| 向后兼容性 | 低 | 通过编译选项控制，默认保持现有行为 |
+
+---
+
+## 8. 参考资料
+
+### 相关源文件
+
+- `lauxlib.c` - 辅助库（文件加载）
+- `ldebug.c` - 调试信息处理
+- `lobject.c` - 对象操作（路径格式化）
+- `lobject.h` - Proto 结构体定义
+- `ldump.c` - 字节码转储
+- `lundump.c` - 字节码加载
+
+### Lua 官方文档
+
+- Lua 5.4 Reference Manual: §4.7 Error Handling
+- Lua Debug Library: debug.getinfo()
+
+---
+
+## 附录：完整实现示例
+
+### A.1 相对路径转换函数
+
+```c
+/* lauxlib.c */
+
+#define LUA_USE_RELATIVE_PATHS  /* 启用相对路径 */
+
+#ifdef LUA_USE_RELATIVE_PATHS
+
+/* 获取规范化的绝对路径 */
+static int get_realpath(const char *path, char *resolved, size_t size) {
+#if defined(_WIN32)
+  return _fullpath(resolved, path, size) != NULL;
+#else
+  char *result = realpath(path, NULL);
+  if (result == NULL) return 0;
+  strncpy(resolved, result, size - 1);
+  resolved[size - 1] = '\0';
+  free(result);
+  return 1;
+#endif
+}
+
+/* 计算相对路径 */
+static const char* make_relative_path(const char *filename) {
+  const char *base = getenv("LUAC_BASE_PATH");
+  if (base == NULL)
+    return filename;  /* 未设置基准路径，保持原样 */
+
+  char abs_file[1024], abs_base[1024];
+  if (!get_realpath(filename, abs_file, sizeof(abs_file)))
+    return filename;  /* 无法解析，保持原样 */
+  if (!get_realpath(base, abs_base, sizeof(abs_base)))
+    return filename;
+
+  size_t base_len = strlen(abs_base);
+  if (strncmp(abs_file, abs_base, base_len) == 0 &&
+      (abs_file[base_len] == '/' || abs_file[base_len] == '\\')) {
+    return abs_file + base_len + 1;  /* 返回相对部分 */
+  }
+
+  return filename;  /* 不在基准路径下 */
+}
+
+#endif  /* LUA_USE_RELATIVE_PATHS */
+
+
+LUALIB_API int luaL_loadfilex (lua_State *L, const char *filename,
+                               const char *mode) {
+  /* ... 省略前面的代码 ... */
+
+#ifdef LUA_USE_RELATIVE_PATHS
+  const char *source_path = make_relative_path(filename);
+  lua_pushfstring(L, "@%s", source_path);
+#else
+  lua_pushfstring(L, "@%s", filename);
+#endif
+
+  /* ... 省略后面的代码 ... */
+}
+```
+
+### A.2 运行时路径扩展
+
+```c
+/* ldebug.c */
+
+/* 扩展相对路径为绝对路径（用于错误报告） */
+static TString* expand_source_path(lua_State *L, TString *source) {
+  const char *src = getstr(source);
+  if (src[0] != '@' || src[1] == '/')
+    return source;  /* 不是文件或已经是绝对路径 */
+
+  const char *base = getenv("LUA_SOURCE_BASE");
+  if (base == NULL)
+    return source;  /* 未设置基准路径 */
+
+  /* 拼接路径 */
+  const char *rel = src + 1;  /* 跳过 @ */
+  size_t base_len = strlen(base);
+  size_t rel_len = tsslen(source) - 1;
+  size_t total = base_len + 1 + rel_len + 1;  /* base + / + rel + @ */
+
+  char *full = luaM_malloc(L, total);
+  snprintf(full, total, "@%s/%s", base, rel);
+
+  TString *result = luaS_new(L, full);
+  luaM_free(L, full);
+  return result;
+}
+
+l_noret luaG_runerror (lua_State *L, const char *fmt, ...) {
+  CallInfo *ci = L->ci;
+  const char *msg;
+  va_list argp;
+  luaC_checkGC(L);
+  pushvfstring(L, argp, fmt, msg);
+  if (isLua(ci)) {
+    TString *source = ci_func(ci)->p->source;
+#ifdef LUA_EXPAND_SOURCE_PATHS
+    source = expand_source_path(L, source);
+#endif
+    luaG_addinfo(L, msg, source, getcurrentline(ci));
+    setobjs2s(L, L->top.p - 2, L->top.p - 1);
+    L->top.p--;
+  }
+  luaG_errormsg(L);
+}
+```
+
+---
+
+**文档版本：** 1.0
+**创建日期：** 2025-11-10
+**适用版本：** Lua 5.4.x