vibe_coding/.cursor/skills/env-setup/SKILL.md

name, version, description

name	version	description
env-setup	2.0.0	初始化 PHP Hyperf + Vue 3 双栈开发环境。当需要项目初始化、环境配置或安装依赖时使用。含 Docker Compose 和数据库初始化。

🔧 Environment Setup (PHP Hyperf + Vue 3 Dual Stack)

触发条件

用户要求初始化项目环境、配置开发工具链、设置环境变量。

执行流程

1. 检测系统依赖

echo "=== System Dependencies ==="

# PHP
php -v 2>/dev/null && echo "✅ PHP installed" || echo "❌ PHP not found (need >= 8.1)"

# Swoole
php -m 2>/dev/null | grep -i swoole && echo "✅ Swoole installed" || echo "❌ Swoole not found (need >= 5.0)"

# Composer
composer --version 2>/dev/null && echo "✅ Composer installed" || echo "❌ Composer not found"

# Node.js
node -v 2>/dev/null && echo "✅ Node.js installed" || echo "❌ Node.js not found (need >= 20)"

# npm
npm -v 2>/dev/null && echo "✅ npm installed" || echo "❌ npm not found"

# Docker
docker --version 2>/dev/null && echo "✅ Docker installed" || echo "⚠️ Docker not found (optional for local dev)"

# Docker Compose
docker compose version 2>/dev/null && echo "✅ Docker Compose installed" || echo "⚠️ Docker Compose not found"

2. 后端初始化 (PHP Hyperf)

cd Case-Database-Backend

# 安装 PHP 依赖
composer install

# 复制环境变量
if [ ! -f ".env" ] && [ -f ".env.example" ]; then
    cp .env.example .env
    echo "✅ .env created from .env.example"
    echo "⚠️ Please fill in required values: DB_HOST, DB_DATABASE, REDIS_HOST, JWT_SECRET"
fi

# 验证 Hyperf 启动
php bin/hyperf.php start --dry-run 2>/dev/null || php bin/hyperf.php di:init-proxy

3. 前端初始化 (Vue 3 + Vite)

for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
  echo "=== $dir ==="
  cd $dir
  
  # 安装 Node 依赖
  npm install
  
  # 复制环境变量
  if [ ! -f ".env.local" ] && [ -f ".env.example" ]; then
      cp .env.example .env.local
      echo "✅ .env.local created from .env.example"
  fi
  cd ..
done

4. 数据库初始化

cd Case-Database-Backend

# 运行迁移
php bin/hyperf.php migrate

# 运行种子（如有）
php bin/hyperf.php db:seed

5. Docker Compose 启动（可选）

# 一键启动全部服务
docker compose up -d

# 验证服务状态
docker compose ps

6. 初始化工具链

工具	配置文件	前端/后端
jsconfig	jsconfig.json	前端
ESLint	.eslintrc.* / eslint.config.*	前端
Prettier	.prettierrc	前端
Husky	.husky/	全栈
PHPStan	phpstan.neon	后端
PHP CS Fixer	.php-cs-fixer.php	后端

7. 验证环境

echo "=== Backend Verification ==="
cd Case-Database-Backend
php -v
composer --version
php bin/hyperf.php --version 2>/dev/null || echo "Run: php bin/hyperf.php start"

echo ""
echo "=== Frontend Verification ==="
for dir in Case-Database-Frontend-user Case-Database-Frontend-admin; do
  echo "=== $dir Verification ==="
  cd $dir
  node -v
  npm -v
  npm run build --dry-run 2>/dev/null || echo "Run: npm run dev"
  cd ..
done

echo ""
echo "=== Services ==="
docker compose ps 2>/dev/null || echo "Docker Compose not running"

关键环境变量

后端 (.env)

变量	说明	示例
APP_NAME	应用名称	MyApp
APP_ENV	环境	dev / production
DB_HOST	MySQL 主机	127.0.0.1
DB_PORT	MySQL 端口	3306
DB_DATABASE	数据库名	myapp
DB_USERNAME	数据库用户	root
DB_PASSWORD	数据库密码	(Secret)
REDIS_HOST	Redis 主机	127.0.0.1
REDIS_PORT	Redis 端口	6379
JWT_SECRET	JWT 密钥	(auto-generate)

前端 (.env.local)

变量	说明	示例
VITE_API_BASE_URL	API 地址	http://localhost:9501
VITE_WS_URL	WebSocket 地址	ws://localhost:9502
VITE_APP_TITLE	应用标题	MyApp

密钥管理最佳实践

原则

• 永不硬编码 — 密钥不进入代码仓库
• 运行时注入 — 密钥在部署/启动时注入，不写入磁盘文件
• 最小权限 — 每个服务只拥有必需的密钥访问权限
• 定期轮换 — 密钥和 Token 设置过期时间并定期轮换

推荐方案（按场景选择）

场景	方案	复杂度
本地开发	.env 文件 (已在 .gitignore)	🟢 低
CI/CD	GitHub Secrets / GitLab Variables	🟡 中
生产环境	HashiCorp Vault / 云 KMS	🔴 高
Docker 部署	Docker Secrets / Compose env_file	🟡 中

本地开发密钥管理

# ✅ .env 文件必须在 .gitignore 中
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore

# ✅ 提供 .env.example 作为模板（无真实密钥）
cp .env .env.example
# 手动清空 .env.example 中的敏感值

Docker 部署密钥注入

# ❌ BAD: docker-compose.yml 中硬编码密钥
services:
  app:
    environment:
      DB_PASSWORD: "my_secret_password"

# ✅ GOOD: 通过 .env 文件注入
services:
  app:
    env_file:
      - .env
    environment:
      DB_PASSWORD: ${DB_PASSWORD}

JWT 密钥生成

# 生成强随机 JWT 密钥
openssl rand -base64 64

# 或使用 PHP
php -r "echo bin2hex(random_bytes(32));"

检查密钥安全

# 检查是否有密钥意外提交到仓库
rg -rn "(?i)(api.?key|secret|password|token)\s*[=:]\s*['\"][a-zA-Z0-9]{8,}" \
  --glob '!vendor/**' --glob '!node_modules/**' --glob '!*.lock' --glob '!.env*'

常见问题排查

问题	解决方案
Swoole 未安装	pecl install swoole 或使用 Docker
Composer 依赖失败	composer clear-cache && composer install
Node 版本不匹配	使用 nvm use 20 切换版本
MySQL 连接失败	检查 .env 中 DB_HOST 和端口，确认 MySQL 正在运行
Redis 连接失败	检查 .env 中 REDIS_HOST，确认 Redis 正在运行
Hyperf 启动失败	检查 runtime/ 目录权限，运行 php bin/hyperf.php di:init-proxy
端口冲突 9501	lsof -i :9501 查看占用进程

验证清单

• PHP >= 8.1 且 Swoole >= 5.0 扩展已安装
• Composer 依赖安装成功
• Node.js >= 20 且 npm 安装成功
• php bin/hyperf.php start 可正常启动 (HTTP 9501)
• npm run dev 可正常启动 (Vite dev server)
• MySQL 和 Redis 连接正常
• 数据库迁移成功
• 所有环境变量已配置