Vue/React项目中public目录资源失效的根因是构建产物引用路径与部署路径错位，如部署子路径/my-app/时publicPath未同步配置为'/my-app/'，导致浏览器请求根路径/logo.svg而实际资源位于/my-app/logo.svg。
跨平台路径转换错误不会导致“静态资源编译失败”——因为静态资源本身不参与编译，而是被构建工具（如 Vite、Webpack）按路径规则搬运或内联。真正出问题的是路径解析逻辑在不同操作系统间不一致，导致资源找不到、404 或构建中断。
为什么 Windows 和 macOS/Linux 的路径拼接会崩
Node.js 的 path.join() 和 path.resolve() 在各平台行为一致，但开发者常误用字符串拼接（如 './assets/' + name）或硬编码反斜杠（'src\images\icon.png'），在 Linux/macOS 下变成非法路径；更隐蔽的是某些插件（如 vite-plugin-static-copy）未启用 os.platform() 感知，导致 glob 模式匹配失败。
- Windows 默认用
分隔符，但 Node.js 内部已统一转为/，手动拼接仍可能触发正则或 shell 解析异常 - Vite 2.x 中
publicDir配置若含\，在 macOS 构建时会被忽略（不报错但资源不拷贝） - Webpack 的
file-loader若publicPath以\结尾，在 CI 环境（Linux runner）中生成的 URL 会多出双斜杠，触发 CORS 或 404
Vue / React 项目中 public 目录资源失效的根因
不是路径“写错了”，而是构建产物中引用路径与部署路径错位。例如：public/logo.svg 在开发时通过 /logo.svg 访问，但打包后若部署到子路径 /my-app/，而 vue.config.js 中 publicPath 仍为 '/'，浏览器实际请求的是 https://site.com/logo.svg 而非 https://site.com/my-app/logo.svg。
- Vue CLI：必须设
publicPath: process.env.NODE_ENV === 'production' ? '/my-app/' : '/' - Vite：改
base配置，且 HTML 中的<link rel="icon">必须用绝对路径（/my-app/favicon.ico），否则被当成相对路径二次拼接 - React（CRA）：无法运行时改
PUBLIC_URL，需构建前设环境变量GENERATE_SOURCEMAP=false PUBLIC_URL=/my-app/ npm run build
Go 二进制中嵌入静态文件时路径失效
Go 1.16+ 的 embed.FS 是安全的，但若你仍在用 os.Open("./static/index.html")，那问题不在“跨平台”，而在工作目录不可控——二进制在哪执行，. 就指向哪，和源码位置完全无关。
- 别依赖
os.Getwd()，它返回当前 shell 的 pwd，不是二进制所在目录 - 正确做法：用
os.Executable()获取二进制路径，再用filepath.Dir()得到目录，最后filepath.Join(dir, "static") - 更彻底方案：直接
//go:embed static/*，然后fs.ReadFile("static/index.html")，完全绕过路径解析
ffmpeg-static 在 CI 中下载失败的路径陷阱
不是 ffmpeg 二进制路径错了，而是 ffmpeg-static 的自动下载机制依赖 process.env.HOME 或 os.tmpdir() 存放缓存，而某些 CI 环境（如 GitLab Runner Docker executor）的 HOME 为空或只读，导致解压失败、路径不存在、权限拒绝三连。
- 显式指定缓存目录：
FFMPEG_STATIC_CACHE_DIR=/tmp/ffmpeg-cache npm install ffmpeg-static - 确保 CI 步骤中该路径可写，且
npm install前已mkdir -p /tmp/ffmpeg-cache - 若用 pnpm，还需加
PNPM_HOME=/tmp/pnpm，避免多层嵌套路径触发 Windows 长路径限制（即使在 Linux runner 上）
最易被忽略的一点：路径问题往往不是单点故障，而是链式失效——一个地方用了硬编码路径，导致构建产物路径错，进而让 runtime 的 fetch 请求 404，最后被误判为“编译失败”。排查时优先检查构建日志里是否真有 ERROR in static asset 类报错，还是只有浏览器控制台的 404；前者看配置，后者看部署上下文。
