1. Linux 桌面下 VSCode 调试 Lua 脚本为什么总卡在第一步
如果你在 Linux 桌面环境里写 Lua，大概率遇到过这种场景：脚本用lua main.lua能跑，但一旦想在 VSCode 里打断点、看变量、单步执行，就发现要么扩展装完没反应，要么launch.json里luaexe路径写错，要么断点显示灰色空心圆根本不命中。Lua 调试在 Linux 下不像 Python、Node 那样开箱即用，核心原因是调试器需要和 Lua 解释器、C 模块搜索路径、动态库加载路径三者对齐，任何一处不对，调试会话就起不来。
这篇面向的是刚接触 Linux + VSCode + Lua 的入门读者，目标很明确：从装扩展、生成launch.json，到断点命中、查看变量与调用栈，一次跑通本地调试链路。我会给出可以直接复制的launch.json与settings.json片段，并把每一步的验证动作写清楚。文中还会顺带说明如何把模型调用相关的配置统一到 TaoToken 的接入方式上，方便你在调试脚本时也能顺手验证网络请求类逻辑。
先说清楚调试链路长什么样。VSCode 本身不理解 Lua，它通过 Debug Adapter Protocol 和调试扩展通信；actboy168.lua-debug这个扩展扮演适配器角色，它内部依赖luamake构建出的调试宿主，再通过luaexe启动你的脚本，注入调试钩子。所以真正决定成败的是三样东西：扩展是否正确安装、luaexe是否指向真实解释器、path/cpath是否覆盖了你require的模块。很多人卡住不是不会写配置，而是不知道这三者之间的依赖关系。
我实测下来，Linux 下最常见的失败不是扩展没装，而是luaexe写成了lua5.4但系统里只有lua5.1，或者cpath没包含.so所在目录导致require直接报错，调试器还没走到断点就退出了。下面按顺序把每一步拆开，你跟着做即可。
2. TaoToken 前置准备：装扩展、拿 Key、配好 Base URL
在正式写launch.json之前，先把环境底座搭好。这一节解决三件事：安装 Lua 调试扩展、确认 Lua 解释器、准备好 TaoToken 的接入信息。TaoToken 在这里的角色是统一的模型接入入口，当你的 Lua 脚本需要发起 HTTP 请求调用模型时，可以直接把 Base URL 指向它，省去自己维护多套地址的麻烦。
2.1 安装 actboy168.lua-debug 扩展
打开 VSCode，进入扩展面板，搜索lua-debug，作者是actboy168，安装它。这个扩展同时会带上extension-path相关能力。命令行方式也可以：
code --install-extension actboy168.lua-debug装完后按Ctrl+Shift+P，输入Lua Debug，如果能看到Lua Debug: Launch Process之类的命令项，说明扩展已生效。如果看不到，重启一次 VSCode。
2.2 确认 Lua 解释器路径
Linux 下 Lua 版本多，先确认你实际用的是哪个：
which lua lua -v典型输出是/usr/bin/lua和Lua 5.1.5或Lua 5.4.x。把这个绝对路径记下来，后面launch.json的luaexe要一字不差地填进去。如果你用的是luajit，路径可能是/usr/bin/luajit，同样记下来。
2.3 准备 TaoToken 接入信息
如果你调试的脚本涉及模型调用，建议统一走 TaoToken。先到控制台创建 API Key：
- 控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console
- API Key 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys
创建后你会拿到一串 Key，形如sk-xxxx。Base URL 统一用：
https://taotoken.net/api注意 API 地址后面不加任何 UTM 参数，保持干净。模型 ID 按你实际要用的填，比如claude-sonnet-4-5这类。这三件套（Base URL + Key + Model ID）在后面配置里会反复出现，先记牢。
提示：Key 不要硬编码进提交到 Git 的脚本里，调试阶段可以放环境变量，例如
export TAOTOKEN_API_KEY=sk-xxxx，脚本里用os.getenv读取。
2.4 安装 ninja 构建工具
lua-debug的调试宿主依赖luamake构建，而luamake需要 ninja。按你的发行版装：
# Debian / Ubuntu sudo apt-get install ninja-build # Fedora sudo dnf install ninja-build # Arch sudo pacman -S ninja # openSUSE sudo zypper in ninja # Alpine sudo apk add ninja装完执行ninja --version能打印版本号即可。这一步很多人忽略，结果扩展装好了但调试宿主没构建成功，断点永远不命中。
3. 可复制配置：launch.json 与 settings.json 完整片段
这一节是全文核心，给出可以直接粘贴的配置。先在工作区根目录建.vscode文件夹，里面放两个文件。
3.1 launch.json 完整配置
{ "version": "0.2.0", "configurations": [ { "name": "Lua Debug: Launch Process", "type": "lua", "request": "launch", "stopOnEntry": true, "luaexe": "/usr/bin/lua", "program": "${workspaceFolder}/main.lua", "cwd": "${workspaceFolder}", "path": "./?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/usr/local/lib/lua/5.1/?.lua;/usr/local/lib/lua/5.1/?/init.lua", "cpath": "./?.so;/usr/local/lib/lua/5.1/?.so;/usr/local/lib/lua/5.1/loadall.so", "arg": [], "consoleCoding": "utf8", "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "${env:TAOTOKEN_API_KEY}", "TAOTOKEN_MODEL": "claude-sonnet-4-5" } } ] }逐字段说明关键项。luaexe必须是你which lua得到的绝对路径，写错直接启动失败。program指向入口脚本，${workspaceFolder}是 VSCode 内置变量，指向你打开的文件夹根目录。path是 Lua 模块搜索路径，对应package.path，分号分隔；cpath对应package.cpath，负责.so动态库查找。stopOnEntry: true表示启动后停在第一行，方便你确认调试器真的挂上了。consoleCoding设成utf8避免中文输出乱码。
env块里我把 TaoToken 的三件套通过环境变量注入，这样脚本里读os.getenv("TAOTOKEN_BASE_URL")就能拿到，不用改代码。注意${env:TAOTOKEN_API_KEY}是引用你系统里已导出的环境变量，避免把 Key 明文写进文件。
3.2 settings.json 完整配置
{ "lua.debug.luaexe": "/usr/bin/lua", "lua.debug.path": "./?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua", "lua.debug.cpath": "./?.so;/usr/local/lib/lua/5.1/?.so", "files.associations": { "*.lua": "lua" }, "editor.tabSize": 2 }settings.json里的lua.debug.*是全局默认值，launch.json里的同名字段会覆盖它。建议两处保持一致，减少排查成本。files.associations确保.lua文件被正确识别语法。
3.3 一个可调试的 main.lua 示例
-- main.lua local function add(a, b) local sum = a + b return sum end local function main() local base_url = os.getenv("TAOTOKEN_BASE_URL") or "https://taotoken.net/api" local model = os.getenv("TAOTOKEN_MODEL") or "claude-sonnet-4-5" print("Base URL:", base_url) print("Model:", model) local result = add(3, 4) print("3 + 4 =", result) local t = { name = "lua", version = _VERSION } for k, v in pairs(t) do print(k, v) end end main()把断点打在local sum = a + b这一行，按 F5 启动调试，如果一切正常，执行会停在这里，左侧变量面板能看到a=3、b=4，调用栈显示add被main调用。
4. 验证请求与成功结果：断点命中、变量与调用栈
配置写完不算完，得实际跑一遍确认链路通。这一节给出完整的验证动作和预期结果。
4.1 启动调试会话
在 VSCode 里打开main.lua，在local sum = a + b行号左侧点一下，出现红点即断点设置成功。按F5，或点左侧调试图标的绿色三角，选择Lua Debug: Launch Process。如果配置正确，底部状态栏变橙，编辑器顶部出现调试工具条，光标停在断点行。
4.2 查看变量与调用栈
停在断点后，左侧「变量」面板展开Locals，应该看到a: 3、b: 4。如果看不到，检查是否真的停在了add函数内部。左侧「调用栈」面板会显示：
add main.lua 2 main main.lua 15点main那一帧，可以切到上层作用域，看到base_url、model等局部变量。这一步能验证调试器不仅能停，还能正确读取作用域。
4.3 单步与继续
按F10单步跳过，sum会被赋值，变量面板里sum: 7出现。按F5继续，程序跑到结束，调试终端打印：
Base URL: https://taotoken.net/api Model: claude-sonnet-4-5 3 + 4 = 7 name lua version Lua 5.1看到这些输出，说明本地调试链路完全跑通。如果你在脚本里加了 HTTP 请求调用模型，把 Base URL 指向https://taotoken.net/api，Key 从环境变量读，就能在调试过程中直接观察请求与响应。
4.4 验证模型调用（可选）
如果你的 Lua 脚本用luasocket或curl发请求，可以在断点处检查请求体。想单独验证模型是否可用，可以直接用模型对话页面测一下：
- 模型对话：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model-chat
在页面里选好模型，发一条测试消息，确认返回正常，再回到脚本里对接，能省不少排查时间。
5. 本篇常见错误排查：401、local proxy failed、reading choices
调试链路跑不通时，报错信息往往很具体。这一节对照真实报错逐个拆。
5.1 401 Unauthorized
如果你在脚本里调用模型接口收到 401，先检查 Key 是否正确传入。常见原因是环境变量没导出，os.getenv返回nil，请求头里 Authorization 为空。验证方法：
echo $TAOTOKEN_API_KEY如果为空，执行export TAOTOKEN_API_KEY=sk-xxxx后重启 VSCode（VSCode 启动时继承环境变量，改完要重启才生效）。另外确认 Base URL 是https://taotoken.net/api，不要多加斜杠或路径。
5.2 local proxy failed
这个报错通常出现在调试器启动阶段，提示本地代理连接失败。原因多是luaexe路径错误或调试宿主没构建成功。排查顺序：先which lua确认路径，再检查扩展是否完整安装。如果扩展目录里缺少构建产物，重新加载窗口（Ctrl+Shift+P→Developer: Reload Window）让扩展重新初始化。
5.3 reading choices 相关报错
当脚本解析模型返回的 JSON 时报attempt to index a nil value或读取choices字段失败，说明响应结构和你预期的不一致。调试时在请求后打断点，打印原始响应体：
print(response_body)确认返回的是 JSON 还是错误文本。如果是错误文本，多半是 Key 或模型 ID 不对。模型 ID 要和 TaoToken 支持的列表一致，写错会返回错误而不是正常结构。
5.4 断点灰色不命中
断点显示灰色空心圆，说明调试器没把该文件和运行中的脚本关联上。常见原因是program路径和实际执行文件不一致，或者cwd不对导致相对路径解析错位。把program改成绝对路径试一次，或者确认${workspaceFolder}指向的确实是你打开的目录。
5.5 require 模块找不到
报module 'xxx' not found，检查path和cpath是否包含模块所在目录。Lua 的require按package.path顺序查找，漏了目录就找不到。可以在脚本开头打印：
print(package.path) print(package.cpath)对照实际文件位置补齐。
6. 把调试链路固定下来：长期编码与接入文档
一次跑通之后，建议把配置固化，避免换项目重来。launch.json可以提交到仓库，Key 走环境变量，这样团队里其他人拉下来就能用。如果你经常调试涉及模型调用的脚本，把 Base URL、Key、Model ID 三件套统一管理，减少切换成本。
长期做编码和 Agent 类项目的话，可以了解下 Coding Plan：
- Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan
接入细节和参数说明看文档：
- 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc
如果你用的是 Claude Code 这类工具，配置方式类似，同样是 Base URL + Key + Model ID 三件套：
- Claude Code 接入：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claudecode
回到 Lua 调试本身，最后给你一个实用习惯：每次新建项目，先写一个最小main.lua，只做print和一次函数调用，把断点打进去跑通，再往里加业务逻辑。这样一旦出问题，你能立刻判断是环境问题还是代码问题。调试器能停、变量能看、调用栈能切，这三件事成立，剩下的就是写代码的事了。
