go build报cannot find package主因是import路径与go.mod声明的模块名不一致；需确保import语句、replace左侧模块名、本地包go.mod中module声明三者完全匹配，并通过go list -m all验证模块加载。
go build 报 cannot find package：不是路径写错了，是模块没对上
Go 编译器找包时，根本不看文件系统目录结构，只认 import 语句里的字符串和 go.mod 里声明的模块名是否一致。比如代码写了 import "mylib/utils"，但 go.mod 里声明的是 module github.com/user/myproject，那它永远找不到 mylib —— 因为它压根不认为这是个模块。
常见错误现象：
build command-line-arguments: cannot load mylib/utils: module mylib: not found- VS Code 提示 “no required module provides package”，但文件明明就在隔壁目录
-
go list -m all不显示本地模块，哪怕你已经用replace写进去了
关键判断点：先运行 go list -m -f '{{.Path}}' mylib。如果返回空或报错，说明 Go 还没把它当模块；如果返回 mylib，才说明模块注册成功，问题出在 import 路径或 replace 规则上。
replace 指令必须配对：go.mod 里写什么，import 就得写什么
replace 不是“让 Go 去某个文件夹找代码”，而是告诉 Go：“当你看到这个模块路径时，请用我指定的本地路径替代”。它生效的前提是：你 import 的路径，必须和 replace 左侧的模块名完全一致。
实操要点：
-
replace左侧必须是合法模块名（如github.com/yourorg/mylib），不能是相对路径或短名（如./mylib或mylib） -
replace右侧是本地路径，用/分隔，Windows 下也别用\（Go 会自动转换，但\可能导致规则失效） - 被 replace 的模块，其自身
go.mod文件里的module声明必须和左侧完全一致（大小写、拼写、斜杠都不能差） - 执行
go mod tidy后，go.sum里不会出现本地模块的 checksum（正常现象），但go list -m all会显示它已加载
示例：replace github.com/yourorg/mylib => ../mylib
对应代码里必须写 import "github.com/yourorg/mylib/utils"，而不是 import "mylib/utils"。
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
go mod tidy 不自动补 replace，它只管 require
go mod tidy 的作用是同步 require 列表，删掉没用的依赖、补上缺失的远程模块。但它**完全忽略 replace** —— 即使你删了 replace 行，它也不会警告；即使你新加了 replace，它也不会帮你加到 require 里。
所以常见坑：
- 手动加了
replace，但忘了在require中声明该模块（哪怕版本写v0.0.0），go build仍会报 “not found” - 误以为
go mod tidy能修复本地路径，结果反复执行也没用 - 删掉了
require行，只留replace，Go 就当这个模块不存在，直接跳过解析
正确做法：
先确保 require 存在且版本可写（如 github.com/yourorg/mylib v0.0.0），再加 replace；改完后手动运行 go mod tidy，它会保留 require 并校验 replace 是否指向有效模块。
IDE 缓存比 go build 更顽固，重启不如重索引
VS Code 的 Go 插件（gopls）会缓存模块路径映射，有时 go build 已成功，但编辑器仍标红、跳转失败、自动补全不出来。这不是配置错了，是 gopls 没刷新本地模块视图。
实操建议：
- 别急着重启 VS Code，先执行命令面板里的
Go: Restart Language Server - 如果还不行，删掉项目根目录下的
gopls缓存目录（通常是$HOME/Library/Caches/gopls或$HOME/.cache/gopls） - 确认
go env GOMOD输出的是当前项目的go.mod路径，不是父目录或/dev/null—— 后者说明 gopls 没识别到模块根 - Windows 用户注意：如果本地模块路径含中文或空格，gopls 可能解析失败，临时改名测试
最可靠的验证方式始终是终端：go build 成功且无报错，就说明路径链路通了；编辑器问题只是显示层，不影响构建本身。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
