1. 从一次真实的连接拒绝说起你在 Vscode 里装好 SQLTools填完 host、port、user、password点下 Connect结果弹出一行红字ERROR: Error opening connection connect ECONNREFUSED 127.0.0.1:3306。这个报错的意思是客户端确实去敲了本机 3306 端口但没有任何进程在那个端口上应答连接被操作系统直接拒绝。它和「密码错误」「认证插件不支持」是两码事——后者至少能建立 TCP 连接而 ECONNREFUSED 连门都没进去。这个场景特别容易出现在本地开发环境MySQL 装了但没启动、只监听了 socket 没监听 TCP、skip-networking被打开、端口被改成了 3307、或者 Docker 容器里的 MySQL 端口没映射到宿主机。SQLTools 作为 Vscode 里的数据库客户端走的是标准 TCP 连接一旦上面任何一条成立它就会报这个错。这篇内容面向正在用 Vscode SQLTools 连本地 MySQL 的开发者尤其是刚装完 MySQL 8.0、配置完连接骨架却连不上的同学。我会从 SQLTools 的settings.json连接配置讲起把 TaoToken 的统一 Key/API 通道配置思路带进来用于需要走统一入口访问模型或服务的场景然后给出可复制的连接片段和逐项验证动作端口监听、服务状态、认证方式一步步定位到底是哪一环断了。目标很明确——让你照着做就能把 ECONNREFUSED 干掉而不是在搜索引擎里反复横跳。2. 前置准备SQLTools 连接骨架与 TaoToken 统一通道先把工具链理清楚。SQLTools 是 Vscode 的一个数据库客户端插件核心由两部分组成一个是SQLTools主插件另一个是对应数据库的驱动比如SQLTools MySQL/MariaDB。两个都装好侧边栏才会出现 SQLTools 图标才能新建连接。连接信息不是写在某个 GUI 弹窗里就完事SQLTools 会把连接配置持久化到 Vscode 的settings.json中字段名是sqltools.connections。理解这个结构很关键因为后面排查时你要直接改它。那 TaoToken 在这里扮演什么角色它提供统一的 Key 和 API 通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。在本地开发里你可能会用同一套 Key 去访问模型对话、coding plan 或者 console 管理避免每个服务单独配一套凭证。对于 SQLTools 这类数据库连接TaoToken 本身不替代 MySQL但它能帮你把「需要统一鉴权的服务入口」收敛到一处减少配置漂移。如果你需要生成或管理 Key可以走 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。需要看接入细节就看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要对话验证模型通道是否通用模型对话https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期编码或跑 Agent 场景可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。注意TaoToken 是统一 Key/API 通道不是数据库代理也不做灰色中转。MySQL 的连接问题仍然要在 MySQL 本身和网络层解决。3. 可复制的 SQLTools 连接配置片段先给你一份能直接抄的settings.json片段。打开 Vscode按CtrlShiftPmacOS 是CmdShiftP输入Preferences: Open User Settings (JSON)在打开的 JSON 里加入下面这段。如果你只想对当前项目生效就改成.vscode/settings.json。{ sqltools.connections: [ { name: local-mysql-3306, driver: MySQL, server: 127.0.0.1, port: 3306, database: test_db, username: root, password: your_password, mysqlOptions: { authProtocol: default }, previewLimit: 50, connectionTimeout: 10000 } ] }几个字段值得单独说。server用127.0.0.1而不是localhost因为localhost在部分驱动里会走 Unix socket而 SQLTools 的 MySQL 驱动更倾向 TCP用 IP 能避免歧义。port默认 3306如果你改过 MySQL 端口这里必须同步。authProtocol在 MySQL 8.0 下建议先保持default如果遇到ER_NOT_SUPPORTED_AUTH_MODE再考虑改成mysql_native_password或调整用户认证插件。connectionTimeout给 10 秒避免网络慢时误判。如果你用的是 TaoToken 统一通道去访问某些需要鉴权的服务可以在环境变量或项目配置里集中管理 Key而不是散落在各个插件里。比如在.env里写TAOTOKEN_API_BASEhttps://taotoken.net/api TAOTOKEN_API_KEYyour_unified_key然后在需要调用的脚本里读取。这样 SQLTools 管数据库连接TaoToken 管服务鉴权职责分开排查时不会互相干扰。配置改完记得保存然后回到 SQLTools 面板右键连接选Connect。如果还是 ECONNREFUSED别急进入下一节的逐项验证。4. 逐项验证端口、服务、认证三步定位排查 ECONNREFUSED 的核心思路是从「端口有没有人听」倒推到「服务有没有起」再到「认证方式对不对」。下面三步按顺序做基本能覆盖九成情况。4.1 第一步确认 3306 端口是否在监听在终端里执行# Linux / macOS ss -tlnp | grep 3306 # 或者 netstat -tlnp | grep 3306# Windows PowerShell netstat -ano | findstr 3306如果输出里有LISTEN并且地址是0.0.0.0:3306或127.0.0.1:3306说明端口在听。如果什么都没输出那就是 MySQL 没监听 TCP或者根本没启动。这时候继续第二步。4.2 第二步确认 MySQL 服务状态与 skip-networking先看服务有没有跑# systemd 系统 systemctl status mysql # 或者 systemctl status mysqld# macOS Homebrew brew services list | grep mysql如果服务是 stopped先启动它sudo systemctl start mysql服务起来了但端口还是没听大概率是skip-networking被打开了。进 MySQL 查SHOW VARIABLES LIKE skip_networking; SHOW VARIABLES LIKE port;如果skip_networking是ONport是0那 ECONNREFUSED 就找到根因了。skip-networking会彻底关闭 TCP/IP 连接方式只留 socket。修改配置文件MySQL 8.0 在 Ubuntu/Debian 上通常是/etc/mysql/mysql.conf.d/mysqld.cnf在 CentOS 上可能是/etc/my.cnf。加入或修改[mysqld] bind-address 0.0.0.0 port 3306 skip-networking off改完重启sudo systemctl restart mysql再查一次SHOW VARIABLES LIKE skip_networking;确认变成OFFport变成3306。注意MySQL 读取配置文件的顺序是/etc/my.cnf→/etc/mysql/my.cnf→/usr/local/mysql/etc/my.cnf→~/.my.cnf。如果你在多个位置都有配置后面的会覆盖前面的排查时要确认最终生效的是哪一份。4.3 第三步确认认证方式是否匹配端口通了、服务起了连接时可能换成另一个错ER_NOT_SUPPORTED_AUTH_MODE。这是 MySQL 8.0 默认用caching_sha2_password而部分客户端驱动还不支持。解决办法是给用户改成mysql_native_passwordALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY your_password; FLUSH PRIVILEGES;如果你是从其他机器连把localhost换成对应 host比如root%。改完再回 SQLTools 点 Connect通常就能连上了。5. 本篇常见错排查清单下面这些是我在实际排查里反复遇到的坑按出现频率排。错误一改了 my.cnf 但没生效。原因往往是配置文件位置不对或者有更高优先级的文件覆盖了。用mysqld --verbose --help | grep -A 1 Default options可以看到 MySQL 实际读取了哪些配置文件。错误二Docker 里的 MySQL 端口没映射。如果你用 Docker 跑 MySQLdocker run时必须加-p 3306:3306否则宿主机上的 127.0.0.1:3306 根本没有进程监听。用docker ps看 PORTS 列有没有映射。错误三SQLTools 缓存了旧连接。改完配置后右键连接选Disconnect再Connect或者干脆删掉连接重新建。有时候 Vscode 窗口需要重载Developer: Reload Window才会重新读取settings.json。错误四防火墙拦了本地回环。虽然 127.0.0.1 一般不走外部防火墙但某些安全软件会拦截本地端口。临时关掉安全软件试一次能连上就说明是它的问题。错误五端口被其他进程占用。用ss -tlnp | grep 3306看是哪个 PID 在听如果不是 mysqld说明端口被别的程序占了改 MySQL 端口或干掉那个进程。错误六密码里有特殊字符导致 JSON 解析异常。settings.json里密码字段如果包含或\需要转义。建议先用简单密码验证连通性再换复杂密码。错误七TaoToken Key 和服务地址配错。如果你在脚本里同时用了 TaoToken 的统一通道确认TAOTOKEN_API_BASE指向https://taotoken.net/apiKey 从 API Keys 页面获取且没有多余空格。这类问题不会导致 ECONNREFUSED但会让后续请求 401排查时别混淆。6. 接入与验证把通道跑通再收尾数据库连上之后如果你还需要验证 TaoToken 的统一通道是否可用可以先用模型对话页面做一次快速验证https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。确认通道通了再去 API Keys 页面管理凭证https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入细节和参数说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你在跑长期编码任务或 AgentCoding Plan 页面有对应的配置方式https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。需要统一管理多个服务的 Key控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。回到 SQLTools 这边连接成功后你会在侧边栏看到数据库树展开能看到表和字段右键可以跑查询。如果这时候还有报错把错误码和上面第三节的三步验证对照一遍基本都能定位。ECONNREFUSED 127.0.0.1:3306 说到底就是「端口没人听」把监听、服务、认证这三层依次确认问题不会藏太久。
