本地开发环境
开发主题 / 插件 / 模型包前，先把 BangNiCMS 本地跑起来。
- Node.js ≥ 20
- pnpm ≥ 8（必须用 pnpm，不是 npm / yarn）
- PostgreSQL ≥ 14（或 MySQL 8，需要切换 Prisma provider）
- Docker（推荐，自动起依赖）
- Git
git clone https://github.com/miaochi998/BangNiCMS.gitcd BangNiCMSpnpm installmonorepo 结构：
BangNiCMS/├── apps/│ ├── server/ 后端 NestJS│ ├── web/ 前台 Astro│ └── admin/ 后台 Next.js├── packages/│ ├── shared-types/│ ├── sdk/│ └── ...└── infra/ └── scripts/配置环境变量
Section titled “配置环境变量”cp .env.example .env按需要填：
BANGNICMS_DATABASE_URL=postgresql://...BANGNICMS_SERVER_PORT=3000BANGNICMS_WEB_PORT=4321BANGNICMS_ADMIN_PORT=3001启动 / 重启
Section titled “启动 / 重启”必须用提供的脚本：
pnpm restart:local脚本自动：
- 停止已跑的进程
- 启动 Docker 依赖（PostgreSQL）
pnpm install- Prisma generate + migrate + seed
- 启动 server、web、admin
- 健康检查
不要手动 npm run dev——会绕过迁移和健康检查。
| 服务 | URL |
|---|---|
| 后台 admin | http://localhost:3001 |
| 前台 web | http://localhost:4321 |
| API server | http://localhost:3000 |
| API 文档 | http://localhost:3000/api/docs |
默认管理员账号：
- 用户名：
admin - 密码：
admin123（首次登录强制改）
主题源码在 apps/web/src/themes/ 下。
修改代码 → Astro 自动热重载。
# 在 apps/web/src/themes/ 下创建新主题目录cp -r official-site my-new-theme
# 修改 manifest.json + 代码
# 后台「扩展市场 → 主题」上传 zip 测试改插件 / 模型包
Section titled “改插件 / 模型包”类似——在 packages/extensions/ 下开发。
如果改了 Prisma schema：
pnpm prisma migrate dev --name my_change后端 NestJS 默认开 debug 端口 9229，VSCode 配 launch.json：
{ "type": "node", "request": "attach", "port": 9229, "name": "Attach to Server"}浏览器 F12 + 主题代码加 console.log。
| 命令 | 用 |
|---|---|
pnpm restart:local | 完整重启 |
pnpm restart:local:stop | 停止所有服务 |
pnpm restart:local:status | 查看状态 |
pnpm restart:local:logs:server | 查看 server 日志 |
pnpm test | 跑单元测试 |
pnpm test:e2e | 跑 E2E 测试 |
pnpm typecheck | TypeScript 类型检查 |
pnpm lint | 代码 lint |
pnpm build | 生产构建 |
E2E 测试
Section titled “E2E 测试”E2E 测试位于 tests/e2e/：
pnpm test:e2e详见 tests/e2e/README.md。
贡献新功能时必须配套加 E2E 测试。
数据 seed
Section titled “数据 seed”pnpm restart:local 会自动 seed 一些测试数据：
- 默认管理员
- 示例语言
- 示例分类
- 示例产品 / 文章
如果想重置：
pnpm prisma migrate resetpnpm restart:localpnpm install 失败
Section titled “pnpm install 失败”- 检查 Node 版本（≥ 20）
- 清理 node_modules + pnpm-lock.yaml 重装
- 看错误信息——通常是某个依赖兼容问题
restart:local 卡住
Section titled “restart:local 卡住”- 检查端口是否被占用（让脚本停止再重启）
- 看
/tmp/bangnicms-*.log查具体错
数据库连接失败
Section titled “数据库连接失败”- 确认 Docker 启动了
- 确认
.env中的BANGNICMS_DATABASE_URL正确 docker ps看 postgres 容器在跑
改 .env 中的端口配置。不要在代码里硬编码端口。