chore: 导入旧记忆备份供恢复

projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/Windows 本地开发与脚本踩坑.md

@@ -0,0 +1,32 @@
+---
+title: Windows 本地开发与脚本踩坑
+type: experience
+permalink: main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/windows-本地开发与脚本踩坑
+stable_id: 7737eaaf-441e-476e-aea0-42a4d13ae245
+scope: project
+memory_type: experience
+project_id: d44c219a-0b31-4de1-b160-323eb34a4c6a
+usage_profile_id: 7aee455b-24cc-4008-bdaf-443721e6f939
+status: active
+revision: 1
+request_id: artveris-migrate-2026-09-03-exp-02
+created_at: '2026-09-03T03:45:32.371988+00:00'
+updated_at: '2026-09-03T03:45:32.371988+00:00'
+tags:
+- windows
+- powershell
+- dev-script
+- prisma
+- pitfall
+---
+
+- `prisma generate` 报 EPERM rename：运行中的 API 占用 Prisma 引擎 DLL，先停 API（`dev.py --stop`）再生成；`dev.py` 已对 generate 做重试。
+- `EADDRINUSE :::3000` 真因：`nest start --watch` 监视器在子进程被杀后自动重启抢端口；处于 idle 的监视器不监听端口按端口找不到。`_lib.kill_project_servers()` 按命令行特征（项目路径 + nest/vite/dist·main）整树清理；三端子进程加入 KILL_ON_JOB_CLOSE 的 Windows Job（ctypes 需显式 restype/argtypes 否则 64 位 HANDLE 截断）；`SetConsoleCtrlHandler` 拦截 Ctrl+C/关闭统一清理。
+- API `tsconfig.json` include 仅 `src`（含 prisma 会让 tsc 改 rootDir 导致 dist/main.js 错位）；显式 `rootDir: ./src`；前端 tsconfig 去 `baseUrl`，`paths` 用 `@/* -> ./src/*`。
+- MySQL 8 `caching_sha2_password` 冷启动首次鉴权可能失败；另一项目占 3306 会命中错库（曾导致 P1000）。
+- PowerShell 双引号字符串中变量后紧跟半角冒号必须写 `${name}:`，否则 5.1 解析为非法作用域变量。
+- Express 5（Nest 11）SPA 回退路由通配符必须写命名 `/*splat`，否则 path-to-regexp 8 拒绝启动。
+- Vite dev 下 `/admin` 无尾斜杠只提示不跳转，两端 vite.config 各加 `redirectToBase` 插件；admin dev 代理 `/api`、`/uploads`、`^/t/.*`→3000、`/trace`→5174，使 5173 成为与生产一致单入口。
+- 安装向导本地调试：安装成功后 `process.exit` 会掰断 HTTP 致前端 `Unexpected end of JSON input`；`ARTVERIS_INSTALL_MODE=1` 时不 exit，生产延迟 2.5s 退出。`dev.py` 监听根 .env 出现（后端最后一步才写）作为安装完成信号自动切正式模式。
+- Docker 本机拉 docker.io 常不通，需 daocloud/1Panel 镜像或代理预缓存 `node:24-slim`；corepack 需 `COREPACK_ENABLE_DOWNLOAD_PROMPT=0`。
+- 安装向导内部 `throw new Error` 会被全局过滤器替换为“服务器内部错误”，需用 `BusinessException` 透传。