Skip to content
返回构建教程

项目初始化

选择技术栈，搭建目录结构，完成第一次绿色构建。

为什么

项目的第一个小时决定了未来每次改动的成本。一个已经带好构建、测试运行器和部署目标的脚手架，意味着新代码从第一个提交起就可测试、可发布。用空文件夹和临时文件起步的团队，要花数周补 CI、lint 和环境加载——那时习惯已经固化。好的初始化器还编码了团队约定（命名、分层、错误处理），让每个项目从同一基线开始，而非每个开发者的个人偏好。

何时使用

第 0 天，任何功能代码之前。用生成器约 30-60 分钟。仅对 24 小时内会删除的抛弃式原型可跳过。

如何做

1. 从你的 ADR 选技术栈（不要在这里重新争论）
   - 读 docs/adr/0001-tech-stack.md；若不存在，先写它

2. 跑官方生成器，而非随机 GitHub 模板
   - Next.js: npx create-next-app@latest --ts --eslint --tailwind --app
   - Vite+React: npm create vite@latest my-app -- --template react-ts
   - NestJS: npx @nestjs/cli new my-api --package-manager pnpm
   - 接受默认值；以后再分叉，不是现在

3. 写任何功能前验证三盏绿灯
   - npm run build → 退出码 0
   - npm test → 通过（即使是占位测试）
   - npm run lint → 零错误

4. 补生成器漏掉的基线文件
   - .env.example 记录每个变量（.env 永不进 git）
   - .editorconfig、.nvmrc / .tool-versions、.dockerignore
   - README.md 用 3 条命令写"本地如何运行"

5. 第一次提交：脚手架 + 一个复现三盏绿灯的 CI workflow
   - 如果 CI 在第 1 次提交就红，脚手架是坏的——先修再写功能

示例

# Next.js + TypeScript + Tailwind，pnpm
pnpm create next-app@latest my-saas --ts --eslint --tailwind --app --import-alias "@/*"
cd my-saas
pnpm dev   # → http://localhost:3000 绿

# 补基线
cat > .env.example <<'EOF'
DATABASE_URL=postgresql://user:pass@localhost:5432/db
NEXTAUTH_SECRET=  # openssl rand -base64 32
EOF
echo "20.11.0" > .nvmrc

# 验证三盏绿灯
pnpm build && pnpm test && pnpm lint  # 全过

git add -A && git commit -m "chore: 脚手架 next.js + ts + tailwind"

常见问题

  • ⚠用两年前的模板锁定过时依赖——你花第一天升级而不是构建。
  • ⚠跳过测试运行器因为'以后再加'——以后永远不会来，未测试代码堆积如山。
  • ⚠第一次提交就把带真实密钥的 .env 提交，然后要轮换密钥并重写 git 历史。
  • ⚠按博客热度而非团队熟悉度选技术栈——第一个 bug 要多花 3 倍时间修。

最佳实践

  • ✓在 .nvmrc 和 package.json engines 里锁定 Node/包管理器版本，让 CI 和队友精确匹配。
  • ✓让第一个 CI workflow 对任何警告都失败，不只是错误——在第 1 次提交立规矩比第 500 次便宜。
  • ✓把脚手架提交和第一个功能提交分开，这样回退是精准的。
  • ✓README 里用可复制粘贴的命令写'本地如何运行'，而非散文段落。