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

title, type, permalink, stable_id, scope, project_id, memory_type, status, revision, restored_from_commit, created_at, updated_at, tags

title	type	permalink	stable_id	scope	project_id	memory_type	status	revision	restored_from_commit	created_at	updated_at	tags
Windows 本地开发与脚本踩坑	experience	main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/windows-本地开发与脚本踩坑	7737eaaf-441e-476e-aea0-42a4d13ae245	project	d44c219a-0b31-4de1-b160-323eb34a4c6a	experience	active	1	6a6a895eaf	2026-09-23T15:06:51.625369+00:00	2026-09-23T15:06:51.625439+00:00	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 透传。