Bolt.new-any-llm项目Ollama模型连接问题解决方案

在使用Bolt.new-any-llm项目时，许多开发者遇到了无法正确连接本地Ollama模型的问题。本文将深入分析问题原因并提供完整的解决方案。

问题现象

当开发者按照文档配置好环境并启动项目后，控制台会显示"Error getting Ollama models: TypeError: fetch failed"错误。具体表现为：

1. 控制台报错显示ECONNREFUSED连接拒绝
2. 即使选择了Ollama模型，系统仍默认使用claude-3-5-sonnet-latest模型
3. 虽然Ollama API服务正常运行，但前端无法获取模型列表

根本原因分析

经过技术排查，发现这个问题源于Node.js的undici库(现代fetch实现)对localhost解析的特殊处理。在macOS和Windows环境下：

1. localhost默认解析为IPv6地址::1
2. 某些网络配置下，IPv6连接可能不稳定或被拒绝
3. undici库在此情况下会抛出ECONNREFUSED错误

解决方案

要解决这个问题，只需修改.env.local文件中的配置：

# 将原来的localhost改为127.0.0.1
OLLAMA_API_BASE_URL=http://127.0.0.1:11434

这个修改确保了：

1. 强制使用IPv4地址127.0.0.1而非localhost
2. 避免了IPv6地址解析可能带来的问题
3. 保持了与Ollama API的稳定连接

技术原理详解

1. 网络地址解析差异

• localhost是一个主机名，可以解析为IPv4(127.0.0.1)或IPv6(::1)
• 现代操作系统默认优先尝试IPv6连接
• 某些网络环境(特别是开发环境)可能未正确配置IPv6回环接口

2. Node.js网络栈行为

• Node.js的http模块和fetch API底层使用undici
• undici对网络错误处理较为严格
• 当IPv6连接失败时，不会自动回退到IPv4

3. 开发环境特殊性

• 开发服务器(如Vite)通常运行在本地
• 与Ollama服务同处一个物理主机
• 直接使用IPv4地址可以确保最可靠的连接

最佳实践建议

1. 在开发环境中，优先使用127.0.0.1而非localhost
2. 生产环境部署时，考虑使用具体域名或IP地址
3. 对于跨平台项目，应在文档中明确网络配置要求
4. 可以添加连接失败时的自动回退机制代码

扩展思考

这个问题虽然解决方案简单，但反映了现代网络编程中的一些常见陷阱：

1. IPv6过渡期的兼容性问题
2. 不同操作系统对localhost解析的差异
3. 网络库对错误处理的严格程度

理解这些底层原理有助于开发者更好地诊断和解决类似连接问题。