ngx-starter-kit快速上手教程：5步克隆并运行PANTS全栈项目
项目地址: https://gitcode.com/gh_mirrors/ng/ngx-starter-kit ngx-starter-kit 是一个开箱即用的 Angular + NestJS 全栈脚手架（Starter Kit），基于 PANTS 技术栈（PostgreSQL、Angular、NestJS、TypeScript）构建于 Nx 单体仓库之上。本教程面向新手，只需 5 个步骤即可完成克隆、安装、运行，快速体验这套企业级全栈项目。
一、什么是 ngx-starter-kit？
在开始之前，先花 30 秒了解它能为你的项目带来什么：
| 能力 | 说明 |
|---|---|
| 🏗️ Nx 单体仓库 | 前端、后端、共享库统一管理，命令式工作流 |
| 🎨 Angular 14 前端 | 内置 NGXS 状态管理、表单、主题、动画等数十个示例模块 |
| 🚀 NestJS 后端 | 集成 TypeORM、Swagger 文档、Passport 认证、Socket.IO |
| 🐘 PostgreSQL | 通过 docker-compose 一键启动数据库 |
| 🧪 完整测试体系 | Jest 单元测试 + Cypress 端到端测试 |
它的 libs/ 目录下有 30+ 个可复用前端模块（如 libs/admin、libs/dashboard、libs/chat-box），相当于一个现成的 Angular 中后台"样板间"。
二、快速上手的 5 个步骤
第 1 步：克隆 ngx-starter-kit 仓库
打开终端，执行以下命令把项目拉到本地：
git clone https://gitcode.com/gh_mirrors/ng/ngx-starter-kit my-project
cd my-project
⚠️ 环境要求：项目要求 Node.js ≥ v17.4.0、npm ≥ 8.3.1（定义于 package.json 的
engines字段）。建议先运行node -v检查版本。
第 2 步：安装项目依赖
npm install --force
首次安装依赖较多，请耐心等待。安装完成后会自动执行 postinstall 脚本装饰 Angular CLI，让 ng 命令走 Nx 的缓存体系，后续构建会更快。
第 3 步：启动前端开发服务器（新手推荐 mock 模式）
# 推荐：使用内置内存 API（mock），无需后端和数据库
npm run start:mock
浏览器打开 http://localhost:4200/，即可看到完整的 Angular 演示应用。修改任何源码文件都会自动热重载。
如果你想连接真实后端，则改用：
npm run start -- --proxy-config proxy.conf.js
第 4 步：（可选）启动 NestJS 后端 API
后端依赖 PostgreSQL，项目提供了 docker-compose.yml 一键拉起：
# 只启动数据库
docker-compose up postgres
# 启动后端 API（watch 模式）
nx serve api
启动成功后：
- API 地址：
http://localhost:3000 - Swagger 接口文档：
http://localhost:3000/docs - 健康检查：
http://localhost:3000/health/live
完整的后端运行说明可参考 apps/api/README.md。
第 5 步：验证运行结果
- 访问
http://localhost:4200→ 前端首页正常渲染 ✅ - 访问
http://localhost:3000/health/ready→ 后端返回就绪状态 ✅
看到页面渲染成功，恭喜！你已经跑通了整套 PANTS 全栈项目 🎉
三、常用命令速查表
| 场景 | 命令 |
|---|---|
| 生产构建 | npm run build:prod（产物在 dist/ 目录） |
| 单元测试 | npm run test（基于 Jest） |
| 端到端测试 | npm run e2e（基于 Cypress） |
| 代码格式化 | npm run format |
| 依赖关系图 | npm run dep-graph |
| 生成 API 文档 | npm run doc:build |
四、项目结构导览
| 路径 | 内容 |
|---|---|
apps/webapp/ | Angular 前端应用 |
apps/api/ | NestJS 后端服务 |
libs/ | 30+ 个可复用前端共享库 |
docs/ | 完整文档，入口见 docs/SUMMARY.md |
docker-compose.yml | PostgreSQL、Keycloak、Redis 等基础设施编排 |
想深入原理？推荐按文档目录顺序阅读：docs/getting-started/ → docs/concepts/（Store / Actions / State）→ docs/recipes/authentication.md（认证方案）。
五、新手常见问题 FAQ
Q1：报错 The container name "/postgres" is already in use？
上次残留的容器未清理，执行：
docker ps -a
docker rm <容器ID>
Q2：安装依赖很慢或失败？
npm install 时项目使用了 --force 来绕过部分依赖冲突，这是官方 README 推荐做法，属于正常现象。
Q3：我只想体验前端，可以不装 Docker 吗？
可以！用 npm run start:mock 启动内存模拟 API，完全不依赖数据库和后端。
从克隆到跑通全流程，5 个步骤、几分钟时间。ngx-starter-kit 帮你把 Angular 前端与 NestJS 后端的工程化细节全部预置好，你可以把精力专注在业务开发上。现在就动手，开始你的全栈之旅吧 🚀
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
