Guide · 通用

在 Windows 上 Vibe Coding：8 个坑，最难缠的是「看起来成功」

2026-09-25 新手入门Windows实战心得

在 Windows 上和 AI 一起写代码，最费时间的不是红字报错。红字至少告诉你出事了。最费时间的是：命令跑完了、没报错、文件也生成了，结果却是错的。

这类坑大多出在一条缝里：我自己敲命令用的是 Windows PowerShell 5.1，Claude Code 在 Windows 上自己跑命令用的却是 Git Bash。两个终端装在同一台电脑上，语法、路径、编码的规矩各不相同，而 AI 脑子里默认的往往是 Linux 那一套。

下面是我攒下的 8 个坑。有的会老实报错，更多的不会。每个都写清楚：怎么认出来，以后固定怎么写。

坑 1：PowerShell 5.1 没有 &&

最常见的一个。AI 顺手给一句带 && 的命令，比如 npm install && npm run build，我粘进终端，直接报：

标记"&&"不是此版本中的有效语句分隔符。

同一个错，AI 在我这儿犯了三次。原因不难猜：它自己的 shell 是 Bash，写 Bash 语法是本能。而 5.1 和 Bash 不兼容的地方远不止 &&：

想做的事Bash 写法PowerShell 5.1 写法
前一条成功再跑下一条a && ba; if ($?) { b }
临时设环境变量VAR=x cmd$env:VAR="x"; cmd
调用真正的 curlcurlcurl.exe（curl 是 Invoke-WebRequest 的别名）

另外，PowerShell 7 才有的三元 ?:、??、?.，在 5.1 里也都没有。

判断方法：看到解析错误，先问一句「这是 PowerShell 语法吗」。

坑 2：Git Bash 会偷偷改路径

这个坑反过来：有的命令不能在 Git Bash 里跑。

智能备课文档生成系统 的前端部署在根路径，构建时要把基址设成 /。在 Git Bash 里写 VITE_BASE_PATH=/ npm run build，构建顺利完成。打开 dist/index.html，资源引用却成了：

src="/Program Files/Git/assets/…"

Git Bash 底下的 MSYS 层看到一个以 / 开头的值，就「好心」把它换成了 Git 的安装目录。整站资源全部指向一个不存在的地方。

固定写法：这类命令改在 PowerShell 里跑——$env:VITE_BASE_PATH="/"; npm run build。构建完看一眼 dist/index.html，资源路径必须是 /assets/…。 这一步不到十秒，却能在上线前把问题拦下来。

坑 3：一个 Secret，两种写坏的方式

这个网站用 GitHub Actions 自动部署，部署要用的一个 Linux 路径存在 GitHub Secret 里。往 Secret 里写这个路径（下面用占位的 /srv/www/mysite），两种顺手写法我都踩过：

  • 在 Git Bash 里执行 gh secret set：和坑 2 一样，MSYS 把 /srv/www/... 转成了 C:/Program Files/...；
  • 换到 PowerShell，用管道把值传给 gh：路径倒是没被改，可管道在值前面加了一个 UTF-8 BOM——三个看不见的字节。

Secret 写进去以后，谁也看不到原值。写坏了，当场不会有任何提示，要等部署用上它时才出问题。

固定写法：在 Git Bash 里用 printf 走标准输入，既不触发路径转换，也不带 BOM：

printf '/srv/www/mysite' | gh secret set DEPLOY_PATH -R <账号>/<仓库>

判断方法：凡是要把一个值原样交给另一个系统，先数清楚它中途经过了哪几层终端和管道。

坑 4：一行中文注释，整个脚本散架

三个现场，一个病根：

  • 教师智能备课 Skill 的 Windows 安装脚本（.ps1），一运行就报 The string is missing the terminator，没装上；
  • 备课时共用的渲染脚本 render.ps1，AI 给它加了一行中文注释，脚本直接跑歪：输出 rendered 0，文件名只剩一个 .png；
  • 阅珍 的 Windows 一键启动脚本，.bat 里如果写中文注释，在中文 Windows 上实测会散成一堆「不是内部或外部命令」。

病根是编码：PowerShell 5.1 读不带 BOM 的 UTF-8 脚本时按系统编码（中文系统是 GBK）去解析，中文就读坏了；cmd.exe 读 .bat 也按系统 ANSI 代码页逐行读，中文一搅，行就断错了。.bat 还有一个附带的坑：LF 行尾会让 goto :label 失效。

有意思的是，BOM 在坑 3 里是祸首，到这里反而是解药：.ps1 另存为「UTF-8 带 BOM」，5.1 就能认对。但更省心的是不让编码有机会出错：

固定写法：.ps1 和 .bat 只用 ASCII 字符，.bat 用 CRLF 行尾；中文说明统统放进 README。

坑 5：压缩包里的中文文件名

给生图 Agent 打任务包时，包里全是中文文件名。PowerShell 5.1 自带的 Compress-Archive 打出来的 zip，拿到别的系统或网页端解压，中文名可能变成乱码。

固定写法：用 Python 的 zipfile 打包，它会写入 UTF-8 标记；更稳的是文件名一律「编号 + 英文或拼音」，中文只出现在文件内容里。跨 Agent、跨系统传文件，后者最省心。

坑 6：git clone 卡住不动

装 GitHub 上的 skill 或仓库时，git clone 会卡住，三分钟没有一点进展。改成直接下载仓库的 zip，1 秒内就有响应，几十 MB 也能正常下完：

curl.exe -o repo.zip https://codeload.github.com/<owner>/<repo>/zip/refs/heads/main

在 PowerShell 里记得写 curl.exe（见坑 1）。下下来的是一份不带 git 历史的快照，装 skill 这种只要文件的场景正合适。

坑 7：python3 找不到，python 又不一定是你要的那个

第三方 skill 的脚本常写 python3。在我的机器上，python3 被解析到微软商店的一个别名，报 Python was not found；真正的解释器叫 python。第三方脚本里写 python3 的地方，一律改成 python。

还有一层：python 能跑，不代表跑对了。备课系统的测试依赖项目虚拟环境，在 Git Bash 里直接敲 python，拿到的是系统装的 3.14，没装项目要用的依赖。跑项目脚本时写全虚拟环境里的解释器路径，比如 .venv/Scripts/python -m pytest。

坑 8：PowerPoint COM 的类型坑

最难发现的一个。用 PowerShell 调 PowerPoint，把幻灯片逐页导出成图片检查：

$slide.Export($path, "PNG", $w, $h)

宽高传字面量没问题；传变量时，PowerPoint 会忽略宽度参数、按默认 DPI 出图，竖版的 A3 海报页被拉变形。

图能出来，只是比例不对。没有报错，没有空文件，只有盯着渲染图才看得出来。

固定写法：数字参数显式强转——$slide.Export($path, "PNG", [int]$w, [int]$h)。

把坑变成规则，而不是写进报告

回头看这 8 个坑，最让我警惕的不是坑本身，而是记下来了照样会再踩：

  • && 那个错，前两次都记进了项目的 progress.md。可那份文件要主动去读，第三次还是犯了。后来这条被写进了每次会话都会自动加载的记忆文件，才没再出现。
  • 坑 2 那次，备课系统的部署文档里记的本来就是 PowerShell 写法，构建还是在 Git Bash 里跑了。
  • 坑 4 的 render.ps1 也是「读过建议还是踩」，经过写在备课 Skill 实测那篇里。

区别在于：报告是写给人看的、要主动去翻；AGENTS.md、CLAUDE.md 和记忆文件，是 AI 每次开工都会自动读的。坑要搬到后者里去（把记忆落到文件里的几种做法，见这一篇）。

如果你也在 Windows 上，新项目开工时可以先让 AI 自己把环境摸一遍，再写这一节：

先别写代码。请把这台 Windows 电脑的环境摸一遍：我平时用的终端是 PowerShell 还是 Bash、什么版本；你自己执行命令用的是哪个 shell；python、python3、node、git 各自指向哪里、什么版本；Git Bash 会不会改写以 / 开头的参数；脚本文件该用什么编码和行尾。探测不出来的就直接问我。然后在 AGENTS.md（Claude Code 用 CLAUDE.md）里写一节「环境说明」，每条写成「现象 → 固定写法」，只写这台机器上实际验证过的，没验证的标「未验证」。以后给我任何可执行命令之前，先对照这一节检查一遍。

按我这台机器的情况，这一节整理出来大概是这样：

## 环境说明（Windows）
- 我的终端是 PowerShell 5.1：不用 && 和 ||，改用 ; 和 if ($?) { }；环境变量写 $env:X="值"；真 curl 写 curl.exe
- 你的 Bash 工具是 Git Bash：以 / 开头的值会被改成 Windows 路径。前端构建一律在 PowerShell 里跑，构建后检查 dist/index.html 是 /assets/…
- 往 Secret、配置里写含 / 的值：只用 Git Bash 里的 printf 走标准输入，不走 PowerShell 管道
- .ps1 / .bat 只用 ASCII，.bat 用 CRLF；中文说明放 README
- 打包含中文文件名的 zip 用 Python zipfile，不用 Compress-Archive
- clone GitHub 卡住就改下 codeload zip
- 解释器叫 python 不叫 python3；跑项目用 .venv 里的 python
- PowerPoint COM 的数字参数一律 [int] 强转

小结

坑看起来实际上
1. &&一条普通命令5.1 直接解析失败
2. Git Bash 设 /构建成功资源路径指向 Git 安装目录
3. 写 Secret值写进去了被改成 Windows 路径，或多了 BOM
4. 脚本里的中文注释只是一行注释报错、跑歪，或整个散架
5. Compress-Archive打包成功换个地方解压，中文名可能乱码
6. git clone正在下载三分钟没有进展
7. python3 / python常见写法指向商店别名，或跑到没装依赖的解释器
8. COM 传变量图导出来了宽度被忽略，竖版变形

在 Windows 上 Vibe Coding，最危险的不是报错，而是「看起来成功」。每认出一个坑，别只在心里记一笔，把它写进 AI 每次开工都会读的那个文件——让规则替你记，而不是靠你自己记。

← 返回指南列表