create-codeforge-app

一行命令创建全栈项目（NestJS + Vue3 + PostgreSQL）。

使用

npx create-codeforge-app my-project

新电脑环境准备

只需要装两样东西：

1. 安装 Node.js

# macOS
brew install node

# Windows
# 去 https://nodejs.org 下载安装

2. 安装 PostgreSQL（二选一）

# 方式A：直接装（推荐）
# macOS
brew install postgresql@16
brew services start postgresql@16   # 启动服务（只需执行一次，开机自动启动）

# 方式B：用 Docker
# macOS
brew install --cask docker
# 装完打开 Docker Desktop
# Windows → 去 https://docker.com 下载安装

💡 brew services start 只需执行一次，之后每次开机 PostgreSQL 会自动启动。如果遇到"PostgreSQL 未启动"的提示，执行 brew services start postgresql@16 即可。

3. 创建项目

npx create-codeforge-app my-shop
# 回答 4 个问题，等 1-2 分钟，自动完成

不需要登录 npm，不需要 clone 仓库，npx 自动下载工具并执行。

功能

• 交互式配置（项目名/标题/数据库名）
• 自动检测 PostgreSQL / Docker 环境
• macOS brew 安装的 PostgreSQL 自动识别用户名
• 可选移动端 H5 骨架
• 可选删除示例模块
• 自动安装依赖、初始化数据库、写入种子数据
• 生成随机 JWT_SECRET
• 清理 git 历史，干净的 init commit

创建完成后

cd my-shop
cd server && npm run start:dev    # 后端 http://localhost:3000
cd client && npm run dev          # 前端 http://localhost:5173

# 管理员账号: [email protected] / admin123
# Swagger 文档: http://localhost:3000/api-docs

开发教程

项目创建后参考以下文档：

• TUTORIAL.md — 新增业务模块的完整教程（5 步流程）
• DEVELOP.md — 本地开发环境搭建 + 代码规范
• DEPLOY.md — 部署指南（服务器 / Railway / Cloudflare Pages）

维护者指南

以下内容仅针对维护者（你自己），普通用户使用 npx 不需要关心。

三者关系

create-codeforge（GitHub 仓库）  →  CLI 工具的源代码，你在这里改代码
        ↓ npm publish（需要 token）
npmjs.com/package/create-codeforge-app  →  CLI 工具的发布版本，用户从这里下载
        ↓ npx（不需要 token）
用户执行 npx create-codeforge-app my-shop  →  自动下载并运行

什么时候需要做什么

| 场景 | 需要做什么 | 需要 token 吗 | |------|-----------|-------------| | 用脚手架创建新项目 | npx create-codeforge-app my-shop | ❌ | | 改了脚手架模板（project-template） | 只需 push 到 GitHub，CLI 自动拉最新 | ❌ | | 改了 CLI 工具代码（create-codeforge） | 需要 npm publish 发布新版本 | ✅ | | token 过期了但不需要发布 | 什么都不用做 | — | | token 过期了且需要发布新版本 | 重新生成 token，再 publish | ✅ |

常见操作

改了脚手架模板（最常见）：

cd project-template
# 改代码...
git add -A && git commit -m "xxx" && git push
# 完事，不需要动 CLI，不需要 npm publish

改了 CLI 工具代码（很少）：

cd create-codeforge
# 改代码...
npm version patch     # 升版本号
npm publish           # 发布到 npm
git add -A && git commit -m "xxx" && git push

Token 过期后如何重新生成

Token 有效期 90 天，过期后只影响 npm publish，不影响任何人使用。

1. 打开 https://www.npmjs.com/settings/codeforge-arch/tokens
2. 点 "Generate New Token"
3. Token name: 随便填，如 publish-2024
4. 勾选 Bypass two-factor authentication (2FA)
5. Permissions: 选 Read and write
6. Select packages: 选 All packages
7. 点生成，复制新 token
8. 终端执行：

echo "//registry.npmjs.org/:_authToken=你的新token" > ~/.npmrc

9. 然后就可以发布了：

cd create-codeforge
npm version patch
npm publish
git push