开发环境搭建与工程脚手架

# macOS / Linux 安装 fnm
curl -fsSL https://fnm.vercel.app/install | bash
 
# 或通过 Homebrew
brew install fnm
 
# 安装 Node.js 22 LTS
fnm install 22
fnm use 22
fnm default 22
 
# 验证
node -v  # v22.x.x

# .node-version
22

# ~/.zshrc 或 ~/.bashrc 追加
eval "$(fnm env --use-on-cd)"

# 启用 Corepack（Node.js 内置的包管理器管理工具）
corepack enable
 
# 验证 pnpm 可用
pnpm -v  # 9.x.x
 
# 如果 Corepack 不可用，手动安装
npm install -g pnpm

{
  "packageManager": "[email protected]",
  "engines": {
    "node": ">=22.0.0",
    "pnpm": ">=9.0.0"
  }
}

# 创建 Nuxt4 项目
pnpm dlx nuxi@latest init ai-video-app
 
# 交互选项说明：
# ✔ Which package manager would you like to use? → pnpm
# ✔ Initialize git repository? → Yes
# ✔ Which UI library would you like to use? → Nuxt UI
# ✔ Which modules would you like to install? → ESLint
 
# 进入项目目录
cd ai-video-app
 
# 安装依赖
pnpm install
 
# 启动开发服务器
pnpm dev

pnpm dev
# Nuxt 4.4.2 with Nitro 2.11.x
# Local:    http://localhost:3000/
# Network:  http://192.168.x.x:3000/

nuxi dev              # 启动开发服务器（HMR 热更新）
nuxi build            # 生产构建
nuxi generate         # 静态站点生成（SSG）
nuxi preview          # 预览生产构建结果
nuxi prepare          # 生成类型声明文件（.nuxt/）
nuxi analyze          # 分析 Bundle 大小
nuxi module add <mod> # 安装 Nuxt 模块
nuxi cleanup          # 清理 .nuxt/ .output/ node_modules/.cache/
nuxi info             # 输出项目环境信息（便于提 Issue）
nuxi typecheck        # 运行 TypeScript 类型检查

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

{
  "name": "ai-video-app",
  "private": true,
  "packageManager": "[email protected]",
  "engines": {
    "node": ">=22.0.0"
  },
  "scripts": {
    "dev": "pnpm --filter @ai-video/web dev",
    "dev:admin": "pnpm --filter @ai-video/admin dev",
    "build": "pnpm -r build",
    "lint": "pnpm -r lint",
    "typecheck": "pnpm -r typecheck",
    "prepare": "husky"
  }
}

{
  "name": "@ai-video/web",
  "dependencies": {
    "@ai-video/shared": "workspace:*"
  }
}

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".output/**", ".nuxt/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {},
    "typecheck": {
      "dependsOn": ["^build"]
    }
  }
}

{
  "recommendations": [
    "Vue.volar",
    "nuxtr.nuxtr-vscode",
    "dbaeumer.vscode-eslint",
    "bradlc.vscode-tailwindcss",
    "antfu.iconify",
    "mikestead.dotenv",
    "EditorConfig.EditorConfig",
    "streetsidesoftware.code-spell-checker"
  ]
}

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
  "eslint.useFlatConfig": true,
  "typescript.tsdk": "node_modules/typescript/lib",
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "tailwindCSS.experimental.classRegex": [
    ["ui:\\s*{([^}]*)}", "['\"`]([^'\"`]*)['\"`]"]
  ]
}

{
  "Nuxt Page": {
    "prefix": "npage",
    "scope": "vue",
    "body": [
      "<script setup lang=\"ts\">",
      "definePageMeta({",
      "  title: '${1:页面标题}',",
      "})",
      "</script>",
      "",
      "<template>",
      "  <div>",
      "    <h1>${1:页面标题}</h1>",
      "    $0",
      "  </div>",
      "</template>"
    ]
  },
  "Nuxt API Route": {
    "prefix": "napi",
    "scope": "typescript",
    "body": [
      "export default defineEventHandler(async (event) => {",
      "  $0",
      "  return { success: true }",
      "})"
    ]
  },
  "Nuxt Composable": {
    "prefix": "ncomp",
    "scope": "typescript",
    "body": [
      "export function use${1:Name}() {",
      "  $0",
      "  return {}",
      "}"
    ]
  }
}

# .env
NUXT_PUBLIC_APP_NAME="AI 视频平台"
NUXT_PUBLIC_API_BASE="/api"
NUXT_AI_API_KEY="sk-xxx"           # 仅服务端可用（无 PUBLIC 前缀）
NUXT_REDIS_URL="redis://localhost:6379"

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // 服务端私有（NUXT_ 前缀自动映射）
    aiApiKey: '',
    redisUrl: '',
    // 客户端公开（NUXT_PUBLIC_ 前缀自动映射）
    public: {
      appName: '',
      apiBase: '',
    }
  }
})

// server/api/ai/generate.post.ts — 服务端使用私有配置
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig()
  // ✅ 服务端可以访问私有配置
  const response = await $fetch('https://api.ai-video.com/generate', {
    headers: { 'Authorization': `Bearer ${config.aiApiKey}` }
  })
  return response
})
 
// app/pages/index.vue — 客户端使用公开配置
// <script setup lang="ts">
// const config = useRuntimeConfig()
// console.log(config.public.appName)  // ✅ 客户端可以访问 public 配置
// console.log(config.aiApiKey)        // ❌ 客户端无法访问私有配置
// </script>

# .nuxtrc（全局，放在 ~ 目录下）
devtools.enabled=true
typescript.strict=true

# .gitignore — 确保敏感文件不入库
.env.local
.env.*.local

# .github/workflows/deploy.yml
env:
  NUXT_AI_API_KEY: ${{ secrets.AI_API_KEY }}
  NUXT_REDIS_URL: ${{ secrets.REDIS_URL }}

# .gitignore
# Nuxt
.nuxt/
.output/
.data/
.nitro/
.cache/
 
# 依赖
node_modules/
 
# 环境变量
.env.local
.env.*.local
 
# IDE
.vscode/*
!.vscode/extensions.json
!.vscode/settings.json
!.vscode/*.code-snippets
 
# 系统文件
.DS_Store
Thumbs.db
 
# 日志
*.log

pnpm add -D -w @commitlint/config-conventional @commitlint/cli

// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat',     // 新功能
      'fix',      // 修复
      'docs',     // 文档
      'style',    // 格式
      'refactor', // 重构
      'perf',     // 性能
      'test',     // 测试
      'build',    // 构建
      'ci',       // CI/CD
      'chore',    // 杂务
      'revert',   // 回退
    ]],
    'scope-enum': [2, 'always', [
      'web',      // 用户前台
      'admin',    // 管理后台
      'shared',   // 共享包
      'config',   // 配置
      'deps',     // 依赖
    ]],
  }
}

git commit -m "feat(web): 添加视频列表页"
git commit -m "fix(shared): 修复类型导出错误"
git commit -m "perf(web): 优化视频列表懒加载"

# 安装
pnpm add -D -w husky lint-staged
 
# 初始化 Husky
pnpm exec husky init

# .husky/commit-msg
npx --no -- commitlint --edit $1

# .husky/pre-commit
npx lint-staged

// package.json（根目录）
{
  "lint-staged": {
    "*.{ts,vue}": ["eslint --fix"],
    "*.{json,md,yml}": ["prettier --write"]
  }
}

# .editorconfig
root = true
 
[*]
charset = utf-8
end_of_line = lf
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true
 
[*.md]
trim_trailing_whitespace = false