---
title: 构建、测试与本地开发硬约束
type: rule
permalink: main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/构建、测试与本地开发硬约束
stable_id: e1b8d25d-f638-4fbe-8a8d-0eda8f2d7d46
scope: project
project_id: d44c219a-0b31-4de1-b160-323eb34a4c6a
memory_type: rule
status: active
revision: 1
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
created_at: '2026-09-23T15:07:59.849331+00:00'
updated_at: '2026-09-23T15:07:59.849393+00:00'
tags:
- build
- test
- dev
- windows
---

- 包管理器锁定 `pnpm@10.28.0`（根 package.json `packageManager`，corepack 激活）；Node 最低 20.11.1，推荐 24 LTS。原生依赖（prisma/sharp）在根 `pnpm.onlyBuiltDependencies` 放行。
- 本地启动：`python scripts/dev.py`（自动进 .venv；无 .env 进安装向导；`--stop` 停服；`--no-seed` 跳过种子）。端口 api 3000 / admin 5173 / client 5174。
- 验证基线：`pnpm build`（全量）、`pnpm --filter @artveris/api test`（后端单测）、Prisma `format/validate/generate`。改 admin/client 文案后必须校验中英文语言包键数量一致。不要在文档中固化测试数量。
- Prisma CLI 手动执行需 `pnpm --filter @artveris/api exec dotenv -e ../../.env -- prisma <cmd>`，否则报 DATABASE_URL 未找到。
- `nest start --watch` 运行中勿删 `apps/api/dist`，也勿在此时跑 `nest build`/`build.py`（会清空重建 dist 导致 dev API 崩）；打升级包前先停本地 API，打完再拉起。
- Windows PowerShell 5：`&&` 不可用（用 `;` 或分步执行）；读中文输出前设 `[Console]::OutputEncoding = UTF8`；ps1 脚本正文用纯 ASCII（UTF-8 无 BOM 的中文会被解析乱码）。
- 改后端 enum/模型需同步 `packages/shared/src/enums.ts` 并新增 Prisma 增量迁移（不改已发布基线 `20260715000000_init`）；运行时可配项走系统设置而非硬编码。
- `docs/系统测试信息.md`（真实凭据）、`.env`、`scripts/.dev.local.json`、`.deploy/` 必须保持 gitignore，绝不提交或输出内容。