构建失败主因是Docker Desktop在Windows上未对齐Linux语义，关键在路径、权限、shell解释器、文件编码及WSL2环境配置。需检查脚本换行符（CRLF→LF）、解释器路径、显式安装依赖、避免Windows路径、确认WSL2网络与资源、排除settings.json的BOM编码问题。
构建时执行脚本失败，绝大多数情况不是脚本本身写错了，而是 Docker Desktop 在 Windows 上的运行环境没对齐 Linux 语义——特别是路径、权限、shell 解释器和文件编码这几个点卡得最死。
Windows 下 docker build 中 RUN 脚本找不到命令或报错“no such file or directory”
这是最典型的 WSL2 环境错位现象：你在 Windows 上写的 shell 脚本（比如 build.sh），直接 RUN ./build.sh，结果提示 /bin/sh: 1: ./build.sh: not found。表面是文件不存在，实际是换行符或解释器路径问题。
- 检查脚本第一行是否为
#!/bin/sh或#!/usr/bin/env bash；Windows 记事本保存的脚本默认带 CRLF 换行，Linux 容器里/bin/sh会把\r当作命令名的一部分，导致解析失败 - 用
file build.sh（在 WSL2 终端中执行）确认换行符类型，输出含CRLF就必须转成 LF - 推荐编辑方式：用 VS Code / Notepad++ 打开脚本 → 底部状态栏切换 “LF” → 保存；或用命令批量修复：
sed -i 's/\r$//' build.sh - 避免在
RUN中直接调用 Windows 路径下的脚本，例如RUN C:\scripts\build.bat—— 容器里根本没有C:盘概念
RUN 执行 Python/Node 脚本时报 ModuleNotFoundError 或 command not found
Docker Desktop 的构建过程在 WSL2 的 Linux 发行版中执行，但你本地 Windows 的 Python/Node 环境完全不可见。所有依赖必须显式安装进镜像，不能靠宿主机 PATH。
- 不要假设
python3或node已存在：基础镜像如alpine默认不带 Python，debian:slim可能只有python（即 Python 2） - 显式声明解释器版本并安装依赖：
RUN apt-get update && apt-get install -y python3-pip && pip3 install requests - 用绝对路径调用可执行文件，比如
RUN /usr/bin/python3 script.py，避免因PYTHONPATH或软链接缺失导致找不到模块 - 注意 Windows 用户常忽略的大小写问题：脚本名写成
Script.py但在RUN中写script.py，Linux 文件系统区分大小写，直接报错
构建时脚本执行卡住、无输出、超时退出
这类问题往往和 WSL2 的资源限制或 Docker Desktop 后台服务通信异常有关，不是脚本逻辑问题，而是环境被静默降级了。
- 检查 Docker Desktop 设置 → Resources → Memory 和 CPUs 是否过低（默认 2GB 内存经常不够跑 npm install 或 pip compile）
- 如果脚本涉及网络请求（如
curl、git clone），确认 WSL2 能正常访问外网：wsl -d docker-desktop进入后执行ping github.com；若失败，可能是公司代理或 DNS 配置未同步到 WSL2 - 某些脚本依赖交互式终端（如需要
stdin输入密码），而docker build默认是非交互模式，会立即 EOF；改用--progress=plain查看真实阻塞点，或用echo "password" | command避免卡住 - 极少数情况是 WSL2 的 init 进程异常，表现为构建中途整个
docker build进程消失：此时执行wsl --shutdown再重试，比反复重试脚本更有效
settings.json 编码错误导致构建流程莫名中断
这个坑非常隐蔽：你改完 Docker Desktop 的 settings.json（比如加了镜像加速地址），重启后 docker build 突然开始报各种奇怪错误，比如 failed to dial unix:///var/run/docker.sock，甚至构建命令根本不响应。
- 根本原因是
settings.json被保存为 UTF-8 BOM 格式，Docker 引擎解析失败后降级为不完整配置，连 socket 通信都可能失效 - 错误特征：Docker Desktop 托盘图标显示“Docker Engine stopped”，但日志里看不到明确报错；
docker info返回空或 500 错误 - 验证方法：用 PowerShell 执行
Get-Content "$env:APPDATA\Docker\settings.json" -Raw | Select-String ""，命中则确认含 BOM - 修复命令（管理员 PowerShell）：
[System.IO.File]::WriteAllText("$env:APPDATA\Docker\settings.json", (Get-Content "$env:APPDATA\Docker\settings.json" -Raw), (New-Object System.Text.UTF8Encoding $false))
真正容易被忽略的是：构建失败的根因常常不在 Dockerfile 里，而在你没意识到的“环境上下文”中——WSL2 的发行版状态、Docker Desktop 的配置文件编码、甚至是你编辑器保存时悄悄加上的 BOM。修之前，先确认 wsl -l -v 显示的发行版是 Running，且 settings.json 是 UTF-8 无 BOM，这两步省掉，后面所有调试都是在雾里打靶。
