Sunqy 文档库

主题

踩坑 · 工具链 ​

分类：踩坑记录 → 工具链 覆盖：fvm、IDE、Git、Node/构建脚本、部署

VitePress 构建：[safe-delete] 操作失败 ​

症状

[safe-delete] 操作失败: ERROR ...\.vitepress\dist\assets: Error during a `trash` operation
build error: [safe-delete] 操作失败

原因 本机 Coding（CodeBuddy）插件 hook 了 Node 的 fs.rmSync，把删除操作改为"移到回收站"；VitePress 清空 dist 时触发该 hook，而回收站操作在本机不被支持，于是失败。

解法 构建前禁用该 hook：

powershell
$env:CODEBUDDY_SAFE_DELETE_ENABLED='0'
npm run docs:build      # 或 npm run deploy

预防 把环境变量写进部署脚本；或在 deploy.md 中固定标注（已记录在部署说明）。

同理，Remove-Item -Recurse -Force 在 PowerShell 中也会被该 hook 拦截，报错 Cannot move ... to the recycle bin。同样用该环境变量绕开，或改用 Git Bash 的 rm -rf。

Git 提交中文乱码（如 瀵艰埗） ​

症状git log 里提交信息显示为乱码汉字。

原因 Windows PowerShell 以 GBK 编码把中文写进 UTF-8 仓库。

解法用 Git Bash 提交（推荐，一劳永逸）：

bash
# 单行
git commit -m "feat: 新增功能"

# 多行（heredoc，避免引号与编码问题）
git commit -m "$(cat <<'EOF'
feat: 新增功能

补充说明
EOF
)"

PowerShell 若必须用：先 chcp 65001 再提交。

预防 已固化为规范：见 git-commit skill（用户级）与 Git 速查 · 中文乱码。

向 Git Bash 传带中文的 heredoc 被破坏 ​

症状 PowerShell 里执行 bash -c "git commit -m \"$(cat <<'EOF' ... )\"" 报语法错误：

重定向运算符后面缺少文件规范
“<”运算符是为将来使用而保留的
一元运算符“-”后面缺少表达式

原因 PowerShell 会先解析 $、<、- 等字符，中文与 heredoc 语法在传递给 bash 前就被破坏。

解法把命令写成 .sh 文件，再用 Git Bash 执行该文件：

powershell
& "D:\sortware\Git\bin\bash.exe" C:/path/to/commit.sh

预防 凡涉及中文 + 多行 + 特殊符号的 git 操作，一律走脚本文件，不在 PowerShell 内联。

node_modules / 日志文件被误提交 ​

症状 仓库体积暴涨，git status 里出现大量本该忽略的文件。

原因.gitignore 只对未跟踪的文件生效——如果文件已经被 git add 跟踪过，后加的忽略规则无效。

解法

bash
# 从索引移除（保留本地文件）
git rm -r --cached node_modules
git rm --cached build.log
git commit -m "chore: 停止跟踪误提交的文件"

预防

  • 项目初始化时就配好 .gitignore
  • 提交前 git status --short 扫一眼
  • 提交时按需 git add <文件>，不用 git add -A

bash deploy.sh 报 WSL 错误 ​

症状

适用于 Linux 的 Windows 子系统没有已安装的分发。

原因bash 指向了 WSL，但本机没装 WSL 分发版。

解法 改用纯 npm 命令（本项目已改）：

bash
npm run deploy

或显式调用 Git Bash：

powershell
& "D:\sortware\Git\bin\bash.exe" "D:/webstromProject/doc/deploy.sh"

预防package.json 的脚本不要依赖 bash，用 npm 命令链保证跨平台。

Cloudflare Pages 部署后页面显示 "Nothing is here yet" ​

症状 部署命令成功了，xxx.pages.dev 却显示空白提示。

原因wrangler pages deploy 默认部署到 Preview 环境，主域名只服务 Production 部署。

解法 部署时加 --branch main（对应生产分支）：

bash
npx wrangler pages deploy .vitepress/dist --project-name sunqy-doc --branch main

本项目 package.json 已内置该参数。

预防deploy:cf 脚本固定带 --branch main；换项目名时同步修改。详见 deploy.md。

wrangler pages deploy 报 Project not found ​

症状

✘ [ERROR] Project not found. ...

原因wrangler pages deploy 不会自动创建项目。

解法

bash
npx wrangler pages project create sunqy-doc --production-branch main

创建后再部署。

预防 换项目名时需重新创建，已记录在 deploy.md。

fvm 命令找不到 / 版本不对 ​

症状fvm: command not found，或 flutter --version 显示的版本与项目要求不符。

解法

bash
dart pub global activate fvm        # 安装
fvm install                          # 安装 .fvm/fvm_config.json 锁定的版本
fvm use <version>                    # 切换并锁定

IDE 需把 Flutter SDK 路径指向 .fvm/flutter_sdk：

  • VSCode settings.json: "dart.flutterSdkPath": ".fvm/flutter_sdk"
  • Android Studio: Languages & Frameworks → Flutter → SDK path

预防 项目 README 写明"所有命令加 fvm 前缀"，见 16 篇。

IDE 无法识别生成的代码（.g.dart 报红） ​

症状.freezed.dart / .g.dart 文件未生成，或生成了但 IDE 报"找不到类"。

原因 未运行 build_runner，或 IDE 未刷新。

解法

bash
fvm dart run build_runner build --delete-conflicting-outputs
# 然后 IDE: File -> Invalidate Caches / Restart

预防 修改带注解的类后立即重新生成；把命令加入项目脚本。

待记录 ​

  • [ ] flutter pub get 因网络/镜像失败的处理
  • [ ] Node 版本与 VitePress 的兼容问题
  • [ ] 部署后 CDN 缓存导致看不到更新
  • [ ] 多 Git 账号/多仓库的凭据冲突