Go 报错 index out of range 怎么解决?切片越界 panic 的 5 大诱因与修复姿势
报错现场
这是 Go 新手从「编译通过」到「一运行就崩」的第一道坎:
panic: runtime error: index out of range [3] with length 3
goroutine 1 [running]:
main.main()
/tmp/main.go:7 +0x1c
报错信息里的两个数字很关键:[3] 是你想要访问的下标,with length 3 是切片当前的实际长度。下标从 0 开始数,长度为 3 的切片合法下标只有 0、1、2,你要访问 [3],自然越界。
这个 panic 在 Go 里属于运行时错误。官方文档《Effective Go》的 Panic 一节明确写道:“When panic is called, including implicitly for run-time errors such as indexing a slice out of bounds or failing a type assertion…"——越界索引会隐式触发 panic,一旦没有 recover 兜底,整个程序直接退出。
复现代码只需几行:
package main
import "fmt"
func main() {
s := []int{1, 2, 3} // 长度为 3
fmt.Println(s[3]) // panic: index out of range [3] with length 3
}
五大诱因
越界 panic 本质只有一句话:下标超出 [0, len(s)) 区间。但落到具体代码里,常见五种写法:
| 诱因 | 典型场景 | 关键特征 |
|---|---|---|
| 空切片/空数组 | make([]T, 0) 或 nil 切片后直接下标访问 |
报错 [0] with length 0 |
| 循环边界写错 | for i := 0; i <= len(s); i++ |
多循环一次,i 取到 len(s) |
| 字符串按字节切 | 中文字符串用下标取字符 | UTF-8 中文占 3 字节,截断乱码或越界 |
| append 后忘接收 | append(s, x) 没赋值回 s |
底层扩容后旧变量长度未变 |
| 并发写共享切片 | 多 goroutine 同时 append/写 | 偶发越界,难复现 |
下面逐个拆解,并给出可复制的修复。
诱因一:空切片直接下标访问
var s []int // nil 切片,len=0
s[0] = 1 // panic: index out of range [0] with length 0
nil 切片和空切片 make([]int, 0) 的 len 都是 0,下标访问必崩。修复:要么 make 时指定长度,要么用 append 追加。
// 写法一:指定长度
s := make([]int, 3)
s[0] = 1
// 写法二:append 追加
var s []int
s = append(s, 1)
诱因二:循环边界多算一次
s := []int{1, 2, 3}
for i := 0; i <= len(s); i++ { // 错误:<= 会访问到 s[3]
fmt.Println(s[i])
}
i <= len(s) 让 i 取到了 len(s),而合法下标最大是 len(s)-1。改成 < 或直接用 range(range 天生不会越界):
for _, v := range s {
fmt.Println(v)
}
诱因三:字符串按字节索引切到中文
s := "你好Go"
fmt.Println(s[0]) // 228,拿到的是 '你' 的第一个字节,不是字符
Go 字符串底层是 UTF-8 字节序列,下标访问拿到的是字节不是字符。中文一个字符占 3 个字节,按字节截断轻则乱码,重则把不完整的 UTF-8 序列转 string 产生异常字符。要按字符遍历,用 []rune:
for _, r := range s { // range 会按 rune 解码,正确处理中文
fmt.Printf("%c", r)
}
诱因四:append 后忘接收返回值
这是最高频、也最隐蔽的一个。append 在容量不足时会重新分配底层数组,返回一个全新的 slice;如果你没有把返回值接住,旧变量还是指向原来的、长度没变的数组:
s := make([]int, 0, 1)
append(s, 1) // 返回值被丢弃,s 仍然是 len=0
fmt.Println(s[0]) // panic: index out of range [0] with length 0
Go 官方文档《Effective Go》专门强调:“append 的结果必须被接收”,因为底层数组可能已经发生了重新分配。修复很简单,把返回值接住:
s = append(s, 1)
fmt.Println(s[0]) // 1
顺带一提,
go vet能抓出「append 结果未使用」这类低级错误,写代码时建议在编辑器里开启 vet 检查。关于 append 与切片扩容的底层细节,可参考站内 深入理解Go Slice底层实现:扩容机制、共享数组与传参陷阱。
诱因五:并发写共享切片
var s []int
var wg sync.WaitGroup
for i := 0; i < 100; i++ {
wg.Add(1)
go func(n int) {
defer wg.Done()
s = append(s, n) // 多个 goroutine 并发写同一个 slice
}(i)
}
wg.Wait()
并发 append 同一 slice 会触发数据竞争,轻则丢数据、重则越界 panic(还可能报 concurrent map writes 的姊妹版)。这是「偶发、难复现」的典型来源。修复方案有三:
- 加锁:用
sync.Mutex包住 append。 - 改用 channel:goroutine 往 channel 发,主 goroutine 收。
- 每个 goroutine 写自己的局部切片,最后再合并——这是最推荐的做法,避免锁竞争:
results := make([]int, 0, 100)
var mu sync.Mutex
for i := 0; i < 100; i++ {
wg.Add(1)
go func(n int) {
defer wg.Done()
mu.Lock()
results = append(results, n)
mu.Unlock()
}(i)
}
wg.Wait()
修复速查表
| 做法 | 适用场景 | 说明 |
|---|---|---|
for _, v := range s |
遍历切片 | range 不会越界,优先使用 |
if i >= 0 && i < len(s) |
动态下标访问 | 访问前做边界判断 |
make([]T, n) 指定长度 |
需要按下标赋值 | 长度够才能直接赋值 |
s = append(s, x) |
动态追加 | 必须接收返回值 |
一个「防御式访问」的通用技巧
如果你拿到的下标来自外部输入(比如用户请求、配置),无法保证一定在范围内,可以在访问前包一层判断,或者封装一个安全的取值函数:
func safeGet(s []int, i int) (int, bool) {
if i < 0 || i >= len(s) {
return 0, false
}
return s[i], true
}
func main() {
s := []int{1, 2, 3}
if v, ok := safeGet(s, 5); ok {
fmt.Println(v)
} else {
fmt.Println("下标越界,已兜底") // 下标越界,已兜底
}
}
小结
index out of range 的根因永远只有一个:访问了 [0, len(s)) 之外的下标。排查时先看 panic 信息里的 [x] 和 with length y,把 x 和 y 对一下就知道是「下标写大了」还是「切片本身是空的」。绝大多数场景用 range + 边界判断 + 正确接收 append 返回值就能根治。
版本说明
- 本文为 Go 语言内建特性(slice 越界 panic),不涉及第三方 SDK,无需核对第三方版本。
- 文中关于 slice 越界隐式触发 panic、append 必须接收返回值的表述,核对自 Go 官方文档《Effective Go》(2026-11-16 核对,文档:https://go.dev/doc/effective_go )。
- 文末可运行示例均基于 Go 1.x 稳定语法,
range、append、make等内建函数自 Go 1.0 起行为一致,兼容当前最新稳定版 go1.27.4(2026-11-10 发布,来源:https://go.dev/doc/devel/release.html )。
相关阅读
- 深入理解Go Slice底层实现:扩容机制、共享数组与传参陷阱
- Go 报错 cannot assign to entry in nil map 怎么解决?nil map 的正确初始化与 4 种修复姿势
- Go 报错 invalid memory address or nil pointer dereference 怎么解决?空指针 panic 排查与 5 种修复姿势
- 《Go 程序设计语言》(Go 语言圣经,机械工业出版社) —— Go 官方团队出品,公认入门第一书
- 《Go 语言实战》(异步图书,人民邮电出版社) —— 实战导向,面试前巩固工程手感
- 《Go 语言编程之旅:一起用 Go 做项目》(博文视点,电子工业出版社) —— 项目驱动入门,从零写出完整应用
- Keychron K1Max 矮轴机械键盘(Mac/Win 双系统,QMK/VIA 开源改键) —— 轻薄矮轴 + 开源固件,程序员桌面常客
- 罗技 MX Master 3S 无线鼠标(Flow 跨屏,静音电磁滚轮) —— 人体工学设计,写代码一整天手不酸
以上链接含京东联盟推广代码;通过链接购买本站可能获得少量佣金,不影响你的购买价格。
每周更新 Go + AI 应用开发实战:AI 面试官完整项目、MCP、Agent 工程化,完整源码随文章首发。
微信扫码,或搜索「Go2AI之路」关注,第一时间获取系列更新与源码,不再错过任何一篇。