Kratos启动卡住90%是主协程被同步阻塞:日志停在“Initializing service...”后无输出,说明未执行到server.Start();常见原因包括NewHTTPServer中同步调用redis.Ping阻塞、viper.ReadInConfig配置加载失败、或main()末尾漏写select{}导致程序立即退出。

Kratos 启动卡住、HTTP/gRPC 接口无响应,90% 是主协程(main goroutine)被同步阻塞,不是框架挂了,而是你的初始化逻辑没做完,http.Server.Serve 或 grpc.Server.Serve 根本没跑起来。
看日志里有没有 “starting server” 或 “listening on”
启动卡住的第一信号:日志停在 Initializing service... 之后,再无输出。这说明程序还没走到 server.Start() 这一步。
- 检查
internal/server/http.go和internal/server/grpc.go中的Start()方法——它是否被调用?有没有被if err != nil { return err }提前 return? - 常见陷阱:在
NewHTTPServer里直接调用了redis.NewClient().Ping(context.Background())这类同步阻塞操作,而 Redis 连接未就绪时会卡死 5 秒以上(默认超时),整个NewHTTPServer就卡住,server.Start()永远不执行 - 另一个高频点:配置加载阶段用了
viper.ReadInConfig()但配置文件路径错、权限不足或 YAML 格式非法,导致ReadInConfig阻塞或 panic 后静默退出(尤其在init()里做这事)
查 main() 函数末尾是否漏了 select{} 或 signal.Notify
Kratos 默认模板的 main() 最后一行是 select{},目的是让主协程常驻,不退出。如果删了它,或者替换成 os.Exit(0)、return,程序会立刻退出,看起来就是“启动完就消失”。
- 确认
cmd/xxx/main.go末尾是select {},而不是log.Fatal(srv.Start())这类错误写法(srv.Start()是阻塞的,但你不能把它放在log.Fatal里——那会掩盖真正的启动失败) - 如果你加了信号监听(如
signal.Notify),确保没有在case 后直接return而没做srv.Stop();更关键的是,别在 signal handler 里调用耗时操作(比如同步写日志文件、发 HTTP 请求),否则主协程会被卡住,无法响应下一个信号
用 pprof 抓 goroutine stack 看主协程卡在哪
启动卡住时,最准的判断方式是开 pprof 查当前所有 goroutine 的栈,重点看 ID=1(主协程)在等什么。
- 启动时加
-http-addr :6060(或确保kratos run启用了 pprof,默认开在:6060/debug/pprof/goroutine?debug=2) -
curl 'http://localhost:6060/debug/pprof/goroutine?debug=2' | grep -A 10 -B 5 "main\|New",找是不是停在redis.(*Client).Ping、sql.Open、grpc.Dial、http.Get或某个sync.Mutex.Lock上 - 特别注意:
database/sql.Open不会真正连 DB,但db.Ping()会;grpc.Dial默认是异步连接,但如果你加了grpc.WithBlock(),它就会同步阻塞直到连上或超时
主协程阻塞往往藏在“看起来很安全”的初始化链路里——比如一个 config loader 里顺手调了 http.DefaultClient.Get 拉远程配置,网络不通就卡死。Kratos 的优雅在于它把服务生命周期交给你控制,但也意味着你得对每一行初始化代码的阻塞性负责。











