errors.Is()是跨平台errno判断的唯一安全方式，因Go 1.19+对errno做了平台别名映射，直接==失效；文件锁需按系统分支实现，Unix用syscall.Flock，Windows用LockFileEx；CGO交叉编译须显式约束头文件；路径、换行符、shell调用等细节必须跨平台适配。
errors.Is() 是跨平台 errno 判断的唯一安全方式
直接用 err == syscall.ECONNREFUSED 在 macOS 或 Windows 上大概率失效。Go 1.19+ 对 errno 做了平台别名映射，syscall.ECONNREFUSED 是常量，而实际返回的 err 是 syscall.Errno 类型实例，底层值可能被重映射过。
正确做法只有一条：统一用 errors.Is()。
-
errors.Is(err, syscall.ECONNREFUSED)—— 跨平台安全 -
errors.Is(err, syscall.EAGAIN)或errors.Is(err, syscall.EINTR)—— 可重试错误识别可靠 - 别写
err == syscall.EWOULDBLOCK，errors.Is()内部已做等价处理
文件锁必须按系统分支实现，标准库不抽象
syscall.Flock() 仅适用于 Unix 系统（Linux/macOS），Windows 完全不支持；Windows 必须用 golang.org/x/sys/windows.LockFileEx()。
光靠 //go:build windows 分文件不够，调用路径和错误处理必须对齐：
立即学习“go语言免费学习笔记（深入）”；
- Linux/macOS：
syscall.Flock(fd, syscall.LOCK_EX|syscall.LOCK_NB) - Windows：
windows.LockFileEx()，注意fd需转为windows.Handle（不能直接传*os.File.Fd()） - 释放锁必须用对应系统 API，建议加
defer并显式忽略错误：_ = syscall.Flock(fd, syscall.LOCK_UN) - 非阻塞尝试失败时，不要
panic，应包装为自定义错误（如ErrLockBusy），便于上层重试或降级
CGO 交叉编译必须显式约束头文件可用性
一旦代码里出现 // #include <sys/epoll.h> 或 import "C"，Go 就不再“透明跨平台”。GOOS=linux go build 不会自动给你装 Linux 头文件，宿主机没有 epoll.h 就直接报错。
双保险构建约束缺一不可：
- 在文件顶部加构建标签：
//go:build cgo && linux - 确保 CI 或本地构建环境预装目标平台头文件（例如 Ubuntu 需
apt install libc6-dev，Alpine 需apk add musl-dev） - 避免在 CGO 代码中混用
syscall常量（如SYS_EPOLL_CREATE1），改用#define或const定义，防止跨平台值错位
路径、换行符、shell 调用不是“小细节”，而是跨平台断裂点
这些看似 trivial 的地方，恰恰是线上故障高发区：
- 路径拼接必须用
filepath.Join("a", "b")，别用"a/b"或"a\b"——os.PathSeparator在 Windows 是'\'，Linux/macOS 是'/' - 换行符别硬写
" "，日志或配置写入需用fmt.Fprintln()或strings.ReplaceAll(s, " ", " ")（仅 Windows 场景） - 调用 shell 命令（如
exec.Command("sh", "-c", ...)）在 Windows 上失败——改用exec.Command("cmd", "/c", ...)或封装os/exec+runtime.GOOS分支 -
os.TempDir()返回值在不同系统差异极大：/tmp（Linux）、/var/folders/...（macOS）、C:Users...AppDataLocalTemp（Windows）——若用于持久化路径，必须额外校验可写性
最易被忽略的是：开发者常以为 “只要没用 syscall 就安全”，但 filepath、os/exec、os/user 这些看似高层的包，底层仍依赖系统行为，稍不注意就跨平台崩掉。
