Neon 与 PlanetScale 连不上：连接串、分支和密码认证失败

Neon 的控制台在 neon.tech，提供可休眠的 Postgres 和分支。PlanetScale 的控制台在 planetscale.com，以数据库分支和部署请求闻名，引擎选项以控制台里实际列出的为准，不要按旧教程认定只有一种。国内打开这两家控制台时，页面可能停在登录框之前；本地程序报错则多半是连接串、角色密码或分支状态，而不是网页没刷出来。

先让控制台完整打开，再复制连接串，最后才跑迁移。把带连接池的地址拿去跑需要会话级功能的迁移，或者把已经轮换的密码留在环境变量里，都会表现为认证失败。套餐、休眠和分支限额会变，以官方最新条款为准。

控制台里两套地址不要混用

连接池地址适合短请求的应用。需要会话锁、临时表或某些迁移命令时，改用直连地址。两条串的主机名不同，不能只改密码。

从控制台打开到迁移通过

• 第一步：先把线路准备好。安装刺猬VPN，自定义用户名和密码注册，不需要邮箱和手机号。免费节点永久免费、不限流量、不限速。连上后再打开 neon.tech 或 planetscale.com，避免登录脚本半截失败。全程 HTTPS+AES 加密传输。
• 第二步：无痕窗口登录控制台。能看到项目列表才算加载完成。白屏时看网络面板里静态资源是否中断，换节点重开，不要在空白页上重置密码。
• 第三步：Neon 进入对应项目和分支，区分直连与池化两条连接串。复制时连同参数一起复制，不要手打主机名。
• 第四步：密码认证失败时，在控制台重置该角色的密码，然后只更新这一处环境变量。旧终端里导出的变量还是旧密码，新开一个终端再试。
• 第五步：提示端点不可用或计算已暂停时，先在控制台把分支唤醒，或执行一次控制台提供的连接测试，再跑本地命令。
• 第六步：PlanetScale 进入目标数据库的分支，用控制台生成的连接信息，不要复用别的分支的密码。要合并结构变更时，按它的部署请求流程，不要直接对生产分支做未评审的改表。
• 第七步：本地迁移指定到开发分支。生产分支的连接串不要放在笔记本的明文文件里。
• 第八步：连接超时先区分是控制台打不开，还是只有数据库端口失败。控制台能开、数据库失败，再查连接串和是否要求加密连接。
• 第九步：手机上看告警邮件即可。改连接串放在电脑。中国大陆区 App Store 不提供 VPN 类应用，安装客户端需外区 Apple ID，在 App Store 搜索「Hedge VPN」，见 iOS 安装教程。

按现象排查：认证、端点和分支

报错原文里的用户名和主机名比感觉可靠。

• password authentication failed：密码或用户名不对，或用了别的分支的角色。重置后更新环境变量，并新开终端。
• 端点不可用或已禁用：分支在休眠、被删或暂停。到控制台看该分支状态，不要连续重试迁移。
• 控制台白屏：页面资源没下完。换节点，无痕窗口重开。
• 迁移在池化地址上失败、直连可以：这条迁移需要直连。把迁移命令的地址换成直连串，应用运行仍可用池化串。
• PlanetScale 拒绝访问：密码已轮换或分支不对。重新生成连接信息，替换所有环境。
• 只有生产失败、预览分支正常：生产环境变量没更新，或部署请求还没合并。看分支状态而不是改本地代码。
• 连接很久才报超时：中途换了节点，或网络中断。固定节点再连一次。
• 证书或加密要求失败：连接串要求加密而客户端没开。按控制台示例补上参数，不要改成不加密。
• 队友能连、你不能：你的网络没打开控制台，或你本地还留着旧密码。先对齐连接串，再对比节点。

线路怎么配

数据库流量通常不大，但迁移中断要重跑。免费节点适合确认控制台能否打开。日常开发用时长套餐，期间不限流量、不限速。刺猬VPN自身不对账号设速率上限。实际可用性取决于当前网络环境。

本地、预览分支和生产

笔记本上只放开发分支的连接串。预览环境用单独分支，生产用单独分支。三个密码不要取同一个。控制台重置密码后，三个地方一起改的做法是错的，只会让你分不清哪一个环境还是旧的。

电脑浏览器适合复制连接串和批准部署请求。手机只看邮件告警。公共网络下不要在别人的电脑登录控制台。

从免费或试用额度迁到正式项目时，先建新项目，再迁数据，最后改应用的环境变量。先改应用会让线上指向一个还没导入数据的空库。旧项目保留到新库完成一次读写之后再删。

连接串里的密码不要贴进工单截图。截图前遮住用户名和主机。轮换后，确认旧密码已经失效，再关闭工单。

和后端平台、云控制台的分工

若应用同时用到 Supabase 或 Firebase，登录和密钥放在哪一边，见 Supabase 与 Firebase 怎么访问。数据库在云厂商控制台里时的登录和区域，见 AWS 控制台打不开怎么办。

Neon 和 PlanetScale 管的是数据库连接和分支。应用托管、对象存储不要写进同一条连接串说明里。密钥只留在部署环境。控制台菜单以官方最新界面为准。

常见报错速查表

高频问答

• 问：池化地址和直连怎么选？答：应用短连接用池化，迁移和要会话状态的命令用直连。两条都从控制台复制。
• 问：重置密码后还是失败？答：环境变量和已经打开的终端里还是旧值。新开终端再试。
• 问：分支休眠会丢数据吗？答：休眠停的是计算，不等于删库。仍以控制台该分支的状态说明为准。
• 问：可以把生产连接串放在笔记本吗？答：不要。生产只放在部署环境。
• 问：免费额度够不够做预览？答：以控制台显示的额度为准，不够就换分支策略，不要靠换节点。
• 问：控制台时好时坏？答：固定节点完成一次登录和复制。实际可用性取决于当前网络环境。

环境变量、迁移和值班

本地、预览和生产三套变量名里都写上分支名，避免复制时贴错。启动应用前先打印主机名里不包含密码的那一段，确认指向的是开发分支。主机名对了再跑迁移。迁移脚本失败时，看它停在第几步，不要整段重跑把已经成功的步骤再执行一次。

连接池满了的表现是短暂拒绝，不是密码错误。先看控制台里的连接数和是否有一个忘记关掉的本地进程占着连接。关掉多余终端，再试一次。把池调得很大不能代替关掉泄漏的连接。

值班时先看是控制台打不开，还是只有应用报认证失败。前者换节点看页面。后者核对最近一次密码轮换有没有漏掉某个环境。轮换清单写下来：控制台、生产、预览、自己的笔记本。笔记本这一项完成后把明文从命令历史里清掉。

备份和恢复按钮在控制台里，不在应用代码里。恢复到新分支试读，确认数据对了再切换应用。直接把生产指到一个刚恢复、还没检查的分支，会把未完成的恢复暴露给用户。本地如果开着图形化的数据库工具，它也会占住连接。迁移报连接过多时，先关掉这些窗口，再看应用本身。工具里保存的密码和命令行里的环境变量是两份，重置之后两份都要改，只改一处会轮流成功、轮流失败。预览环境的数据可以从生产复制结构，不要复制含有真实用户的内容到笔记本。需要样本时用脱敏后的少量数据。只读账号和迁移账号分开。日常查询用权限更小的角色，迁移用单独角色。这样密码泄露时影响面更小。控制台里如果能看到最近一次连接来自哪里，轮换后确认旧密码已经连不上，再宣布轮换完成。应用启动报找不到主机时，先看环境是不是还停在被删除的分支名上，而不是先改代码里的查询语句。删除分支之前，确认没有任何环境变量还写着它的名字。确认完再删，删完在预览环境走一遍读和写。

先分清是网页还是连接串

Neon 或 PlanetScale 连不上，先看控制台能否打开，再看用的是哪一条连接串、哪一个分支。密码重置后必须新开终端。迁移和生产运行可以各用一条地址。

刺猬VPN采用 HTTPS+AES 加密传输，注册不需要邮箱和手机号。免费节点适合确认控制台能否打开，时长套餐在有效期内不限流量、不限速。客户端支持断线保护和按域名的智能分流。找回密码凭支付订单记录。产品限额以官方最新条款为准，实际可用性取决于当前网络环境。