micro-landing-builder

微型落地页构建器

为初创公司创建由配置驱动的 NextJS 落地页。

契约

输入：

• 一个或多个落地页定义：slug、名称、域名、概念和配置
• 目标根目录
• Slug：由小写字母、数字和连字符组成的单一路径段；其他格式均会被拒绝
• 可选的域名映射

输出：

• 生成的落地页应用目录
• app.json 配置文件
• 部署计划；如果明确请求部署，则输出已部署的 URL

创建/修改：

• 本地落地页应用目录
• Vercel 配置文件
• 默认不部署到生产环境

外部副作用：

• 只有在明确请求部署后，才可能部署到 Vercel 并绑定自定义域名

需要确认：

• 在当前工作区之外批量创建之前
• 在部署到生产环境之前
• 在绑定自定义域名之前
• 在覆盖现有落地页目录之前

委派给：

• 单个静态落地页：推荐使用 landing-page-vercel
• 完整产品代码仓库：使用 project-init-orchestrator / npx @shipshitdev/v0
• Vercel 部署：使用 deployment-composer 或 deploy-app

概念

每个落地页都是独立的 NextJS 应用，其中：

• 内容由 app.json 配置文件定义
• UI 使用 shadcn/ui：components.json、components/ui（Button、Card、Badge、Accordion、Input）以及 components/sections 中的落地页区块；它们都会被复制到应用中，因此应用拥有自己的代码
• 主题令牌是 app/globals.css 中的 shadcn CSS 变量（@theme inline）；app.json 中的 theme 会覆盖 --primary、--background 和额外的 --brand 强调色
• 可通过 Vercel 独立部署到任何域名

先决条件

无需预先发布或安装任何内容：脚手架会自行写入 shadcn/ui 配置，并且仅依赖在线 npm 包（Next.js 16、React 19、Tailwind v4、shadcn、radix-ui、class-variance-authority、cn、lucide-react、tw-animate-css）。版本固定在 scripts/scaffold.py 中；修改固定版本前，请使用 npm view <pkg> version 重新检查。需要 Bun 和网络连接以运行 bun install。

用法

# Show help
python3 scripts/scaffold.py --help

# Create a new landing
python3 scripts/scaffold.py \
  --slug mystartup \
  --name "My Startup" \
  --domain "mystartup.com" \
  --concept "AI-powered analytics"

# Light theme (app.json theme.mode "light" with a white background and dark text)
python3 scripts/scaffold.py \
  --slug mystartup \
  --name "My Startup" \
  --theme-mode light

# Custom colors (#rgb, #rgba, #rrggbb or #rrggbbaa); text colors are picked for contrast
python3 scripts/scaffold.py \
  --slug mystartup \
  --name "My Startup" \
  --primary "#00ff00" \
  --background "#f4f4f5"

# Allow outside current directory
python3 scripts/scaffold.py \
  --root ~/www/landings \
  --slug mystartup \
  --allow-outside

生成的结构

mystartup/
├── app.json              # All content/config here
├── package.json          # Next 16, React 19, Tailwind v4, shadcn/ui runtime deps
├── components.json       # shadcn config ("config": "" for Tailwind v4)
├── next.config.ts
├── postcss.config.mjs    # @tailwindcss/postcss (Tailwind v4)
├── tsconfig.json
├── vercel.json           # Vercel deployment config
├── public/
│   └── (images go here)
├── lib/
│   ├── utils.ts          # cn() helper
│   └── theme.ts          # app.json theme -> mode and CSS variable overrides
├── components/
│   ├── ui/               # shadcn: button, card, badge, accordion, input
│   └── sections/         # header, hero, stats, features, pricing, testimonials, faq, cta, footer
└── app/
    ├── layout.tsx        # Applies app.json theme to the shadcn CSS variables
    ├── page.tsx          # Renders sections from app.json
    ├── globals.css       # Tailwind v4 + shadcn tokens: :root, .dark, @theme inline
    └── api/subscribe/    # Waitlist endpoint stub (returns 501 until a provider is wired)

电子邮件收集表单会向 app/api/subscribe/route.ts 提交数据。它会验证地址，并返回 501，直到你在该处接入电子邮件服务提供商，因此表单绝不会谎称已存储实际并未保存的电子邮件。

app.json 配置

落地页完全由 app.json 驱动。完整架构请参见 references/config-schema.md。

{
  "name": "My Startup",
  "slug": "mystartup",
  "domain": "mystartup.com",
  "meta": {
    "title": "My Startup - Tagline",
    "description": "SEO description"
  },
  "theme": {
    "primary": "#4f46e5",
    "accent": "#f59e0b",
    "background": "#0a0a0a",
    "foreground": "#fafafa",
    "mode": "dark"
  },
  "analytics": {
    "plausible": "mystartup.com"
  },
  "sections": [
    { "type": "hero", "headline": "...", "subheadline": "..." },
    { "type": "features", "items": [...] },
    { "type": "pricing", "plans": [...] },
    { "type": "faq", "items": [...] },
    { "type": "cta", "emailCapture": { "enabled": true } }
  ]
}

区块类型

• hero - 主视觉区，包含标题和 CTA 按钮
• stats - 关键指标/数字
• features - 带图标的功能网格
• pricing - 定价方案
• testimonials - 客户评价
• faq - 手风琴式常见问题
• cta - 行动号召，带电子邮件收集功能

批量创建

从模板或 CSV/JSON 文件创建多个落地页：

# From CSV file
python3 scripts/batch_create.py \
  --root ~/www/landings \
  --csv projects.csv \
  --allow-outside

# From JSON file
python3 scripts/batch_create.py \
  --root ~/www/landings \
  --json projects.json \
  --allow-outside

# Clone from existing template
python3 scripts/batch_create.py \
  --root ~/www/landings \
  --template ~/www/landings/template-landing \
  --json projects.json \
  --allow-outside

CSV 格式

slug,name,domain,concept
project1,Project One,project1.com,AI-powered analytics
project2,Project Two,project2.com,Cloud infrastructure

可选主题列（标题会去除首尾空格，且不区分大小写；未知或重复的标题以及单元格数量不符的行都会导致操作中止并报错；文件可以带有 UTF-8 BOM）：primary、accent、background、theme_mode（dark 或 light）。颜色必须严格符合 #rgb、#rgba、#rrggbb 或 #rrggbbaa 格式（不能包含空格；JSON 中不能为空字符串；CSV 空单元格表示“未设置”）。无效行会被跳过，运行会以非零状态码退出。使用 --template 时，颜色和模式会应用到克隆的 app.json；如果给出了新的 background，则会清除继承的 foreground、mode 和 accent（除非你提供新的 accent，否则会重新推导强调色）。

JSON 格式

[
  {
    "slug": "project1",
    "name": "Project One",
    "domain": "project1.com",
    "concept": "AI-powered analytics"
  },
  {
    "slug": "project2",
    "name": "Project Two",
    "domain": "project2.com",
    "concept": "Cloud infrastructure"
  }
]

部署

单个项目

运行 vercel 之前，请确认落地页目录中存在 .vercel/project.json。如果不存在，请停止并让用户手动运行 vercel link——不要在无人值守的情况下运行该命令。

cd mystartup
vercel

带域名的批量部署

将多个项目部署到 Vercel 并绑定自定义域名：

# Deploy with domain mapping
python3 scripts/deploy_vercel.py \
  ~/www/landings/project1 \
  ~/www/landings/project2 \
  --domains-json domains.json \
  --prod \
  --yes

# Single domain
python3 scripts/deploy_vercel.py \
  ~/www/landings/project1 \
  --domain project1.com \
  --prod \
  --yes

域名映射 JSON

{
  "project1": "project1.com",
  "project2": "project2.com"
}

**注意：**在将域名添加到 Vercel 之前，必须先在 DNS 中配置这些域名。Vercel 会提供需要添加的 DNS 记录。

工作流

单个落地页

1. 运行脚手架以创建落地页结构
2. 使用你的内容编辑 app.json
3. 将图片添加到 public/
4. 使用 vercel 部署，或使用 deploy_vercel.py

多个落地页

1. 创建包含项目定义的 CSV/JSON 文件
2. 运行 batch_create.py 生成所有落地页
3. 根据需要自定义每个 app.json
4. 运行 deploy_vercel.py，使用域名部署所有页面

自定义

使用 bunx --bun shadcn@latest add <name> 添加更多 shadcn 组件（这些组件会放在 components/ui 中）。

如需添加自定义区块：

1. 在 components/sections/ 中添加组件
2. 在 app/page.tsx 中导入该组件
3. 在 sectionComponents 映射中，根据组件的 type 注册该组件

在 app.json 的 theme 中更改颜色（primary、accent、background、foreground、mode）。Bun 会在创建脚手架或克隆之前，使用与 app/layout.tsx 相同的解析器验证完整主题。主题无效时，会报告出错的颜色对及对比度；请选择更深或更浅的背景，或移除显式设置的前景色。运行时编辑无效时会发出警告，并使用完整的默认主题。颜色支持带锚点的 #rgb、#rgba、#rrggbb 和 #rrggbbaa；Alpha 通道会规范为不透明的六位十六进制颜色，并发出警告。最终取整后的颜色会用于检查每组文本颜色对的对比度是否达到 4.5:1，以及焦点指示器和输入框边框的对比度是否达到 3:1。除非显式指定，否则会根据背景推断模式；经过审核的表面颜色在任一模式下均可使用。请使用令牌工具，而不要硬编码颜色。有关派生和验证的详细信息，请参阅 references/config-schema.md。

参考

• references/config-schema.md - 完整 JSON 架构
• references/sections-reference.md - 区块类型和属性