Go go-vcard 怎样从文件连续读取多张联系人卡片

Go 里用 github.com/emersion/go-vcard 读取多张联系人卡片时，不需要先把整个文件拆成字符串。打开 .vcf 文件后创建一个 vcard.Decoder，在循环里反复调用 Decode()：每次成功得到一张 Card，返回 io.EOF 时说明文件已经读完。

官方地址：https://pkg.go.dev/github.com/emersion/go-vcard

最小判断规则就是：成功的 Decode() 处理一张卡片；io.EOF 是正常结束；其他错误才是需要保留和处理的解析失败。这样既能连续处理多条记录，也不会把文件末尾误判成异常。

为什么一次 Decode 只能拿到一张卡片

一个 vCard 文件可以连续放置多组 BEGIN:VCARD 到 END:VCARD 的记录。go-vcard 的 NewDecoder 接收一个 io.Reader，而 Decode() 的职责是从当前读取位置解析下一张卡片。因此，文件里有多少组记录，循环就可能成功返回多少次 Card。

这个设计的好处是读取过程可以沿着输入流推进，不必预先把全部联系人复制到一个大数组里。是否保存已经读出的卡片，由业务层根据导入、转换或统计需求决定。

连续读取多张联系人卡片的最小写法

下面的代码把文件生命周期、解码循环和错误分支放在一起。示例只打印每张卡片的首选显示名，实际项目可以在循环中写入数据库、转换成自己的结构体，或继续读取电话和邮箱字段。

package main

import (
	"fmt"
	"io"
	"os"

	"github.com/emersion/go-vcard"
)

func main() {
	// 文件句柄实现 io.Reader，供 Decoder 按顺序消费输入。
	f, err := os.Open("cards.vcf")
	if err != nil {
		fmt.Println("打开 vCard 文件失败:", err)
		return
	}
	defer f.Close() // 无论循环如何结束，都释放文件描述符。

	dec := vcard.NewDecoder(f)
	count := 0
	for {
		card, err := dec.Decode()
		if err == io.EOF {
			break // 文件末尾是正常结束，不是解析错误。
		}
		if err != nil {
			fmt.Println("读取第一个错误位置附近的卡片失败:", err)
			return
		}

		count++
		name := card.PreferredValue(vcard.FieldFormattedName)
		fmt.Printf("第 %d 张：%s\\n", count, name)
	}

	fmt.Println("共读取", count, "张联系人卡片")
}

循环的关键不是判断卡片数量，而是把 Decode() 的返回错误分成三类：没有错误表示拿到一张卡片，io.EOF 表示没有下一张，其他错误表示当前输入无法继续按预期解析。

io.EOF 为什么要单独处理

io.EOF 在这里是读取协议的一部分。它告诉调用方输入已经结束，通常不应该把它打印成“导入失败”。如果把所有非空错误都当成失败，正常读完文件时日志就会多出一条误报警。

相反，解析错误不能被当作结束信号吞掉。遇到其他错误时，可以直接返回，让上层决定是终止整批导入、记录文件位置，还是把任务标记为部分成功。是否跳过坏记录取决于业务容错要求，go-vcard 的基础循环不会替你做这个决定。

读取 FN、TEL 和 EMAIL 时怎么选方法

Card 是由字段名映射到字段列表的结构。只想拿一个优先值时，可以用 PreferredValue；需要保留一个联系人多个电话号码或多个邮箱时，则应使用 Values 取得列表。不能假设每张卡都一定存在姓名、电话或邮箱。

// 读取单值和多值字段时，都先接受字段可能缺失的情况。
name := card.PreferredValue(vcard.FieldFormattedName)
phones := card.Values(vcard.FieldTelephone)
emails := card.Values(vcard.FieldEmail)

fmt.Println("姓名:", name)
for _, phone := range phones {
	// 多个 TEL 字段不能压缩成一个值，否则会丢失联系人信息。
	fmt.Println("电话:", phone)
}
for _, email := range emails {
	// EMAIL 同样可能出现多个，逐项交给后续业务处理。
	fmt.Println("邮箱:", email)
}

字段为空并不等于解析失败：它可能只是原始 vCard 没有填写该属性。导入程序若把姓名当作主键，就应该额外设计缺失姓名的处理策略，而不是依赖 PreferredValue 自动补值。

多张卡片文件的输入边界

下面是一个简化的输入形状，用来说明为什么循环会有多次成功返回。每组记录都拥有自己的开始和结束标记，真实文件还可能包含参数、折行和更多属性。

BEGIN:VCARD
VERSION:3.0
FN:张宁
TEL;TYPE=CELL:13800000001
END:VCARD
BEGIN:VCARD
VERSION:3.0
FN:周远
EMAIL:zhou@example.test
END:VCARD

对于这种文件，第一次 Decode() 处理张宁，第二次处理周远，第三次调用才会收到 io.EOF。如果文件只有一张卡片，第一次成功后第二次就可能直接结束；如果文件为空，也不应把“没有卡片”写成“读取失败”。

什么时候应该保存 Card，什么时候边读边处理

如果任务是把联系人导入数据库，通常可以在循环里完成字段映射和写入，只保留计数与错误信息；如果任务是排序、去重或生成一次性报告，则可以把每张 Card 放进切片，等全部读取完成后再处理。

常见问题：连续读取 vCard 时容易混淆的地方

go-vcard 会一次返回所有联系人吗？

不会。每次 Decode() 返回一张 Card，需要循环读取整个输入，直到 io.EOF。

可以用空的 Card 判断文件结束吗？

不建议。文件结束应以返回的 io.EOF 为准，卡片字段缺失则属于数据内容问题。

为什么不能把 io.EOF 和解析错误一起处理？

因为前者代表正常结束，后者代表输入可能损坏或不符合预期。两者对应的任务状态不同，混在一起会让导入结果难以判断。

多个电话字段应该用 PreferredValue 还是 Values？

只关心首选号码时用 PreferredValue；要保留全部号码时用 Values，并为字段缺失或重复做好业务处理。

一句话总结：用 os.Open 得到输入流，交给 vcard.NewDecoder，循环调用 Decode() 处理每张 Card，把 io.EOF 当作正常结束，把其他错误留给上层处理，就能稳定读取一个文件中的多张联系人卡片。