尧图网页设计 
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装完后按CtrlShiftP输入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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-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_KEYsk-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 启动调试如果一切正常执行会停在这里左侧变量面板能看到a3、b4调用栈显示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/apiKey 从环境变量读就能在调试过程中直接观察请求与响应。4.4 验证模型调用可选如果你的 Lua 脚本用luasocket或curl发请求可以在断点处检查请求体。想单独验证模型是否可用可以直接用模型对话页面测一下模型对话https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-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_KEYsk-xxxx后重启 VSCodeVSCode 启动时继承环境变量改完要重启才生效。另外确认 Base URL 是https://taotoken.net/api不要多加斜杠或路径。5.2 local proxy failed这个报错通常出现在调试器启动阶段提示本地代理连接失败。原因多是luaexe路径错误或调试宿主没构建成功。排查顺序先which lua确认路径再检查扩展是否完整安装。如果扩展目录里缺少构建产物重新加载窗口CtrlShiftP→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 PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan接入细节和参数说明看文档接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你用的是 Claude Code 这类工具配置方式类似同样是 Base URL Key Model ID 三件套Claude Code 接入https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode回到 Lua 调试本身最后给你一个实用习惯每次新建项目先写一个最小main.lua只做print和一次函数调用把断点打进去跑通再往里加业务逻辑。这样一旦出问题你能立刻判断是环境问题还是代码问题。调试器能停、变量能看、调用栈能切这三件事成立剩下的就是写代码的事了。 Linux 下 VSCode 调试 Lua：把 launch.json 改到 TaoToken 的完整配置
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装完后按CtrlShiftP输入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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-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_KEYsk-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 启动调试如果一切正常执行会停在这里左侧变量面板能看到a3、b4调用栈显示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/apiKey 从环境变量读就能在调试过程中直接观察请求与响应。4.4 验证模型调用可选如果你的 Lua 脚本用luasocket或curl发请求可以在断点处检查请求体。想单独验证模型是否可用可以直接用模型对话页面测一下模型对话https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel-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_KEYsk-xxxx后重启 VSCodeVSCode 启动时继承环境变量改完要重启才生效。另外确认 Base URL 是https://taotoken.net/api不要多加斜杠或路径。5.2 local proxy failed这个报错通常出现在调试器启动阶段提示本地代理连接失败。原因多是luaexe路径错误或调试宿主没构建成功。排查顺序先which lua确认路径再检查扩展是否完整安装。如果扩展目录里缺少构建产物重新加载窗口CtrlShiftP→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 PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan接入细节和参数说明看文档接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你用的是 Claude Code 这类工具配置方式类似同样是 Base URL Key Model ID 三件套Claude Code 接入https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode回到 Lua 调试本身最后给你一个实用习惯每次新建项目先写一个最小main.lua只做print和一次函数调用把断点打进去跑通再往里加业务逻辑。这样一旦出问题你能立刻判断是环境问题还是代码问题。调试器能停、变量能看、调用栈能切这三件事成立剩下的就是写代码的事了。