快速开始

项目快速上手图文教程

初始化项目

通过shipany-template-nano-banana源码 去新建项目

下面命令中的my-shipany-project是你新项目名字,注意改下

下面命令是要部署在Vercel上的Clone项目命令


git clone git@github.com:template-code-team/shipany-template-nano-banana my-shipany-project

下面命令是要部署在Cloudflare上的Clone项目命令

此分支基于 Next.js 15.5.5,暂不支持 Next.js 16。


git clone -b cloudfare git@github.com:template-code-team/shipany-template-nano-banana my-shipany-project

clone完毕后进入项目


cd my-shipany-project

安装依赖


pnpm install

启动开发服务器


pnpm dev

点击输出的 Local 地址,在浏览器打开网页:http://localhost:3000 ,即可预览项目

如果你要将新项目提交到自己github仓库,需要做下面动作,上面的Clone会把源代码的.git远程仓库也Clone下来了,需要按照下面执行下命令,要不然你提交不上去

移除原始远程模板项目仓库连接,并创建一个私有的 GitHub 项目仓库。


# 移除原始远程模板项目仓库

git remote remove origin



# 在 GitHub 上创建一个私有仓库,并设置为远程仓库

# 注意:将下面 your-project-name 改成你的项目名称

gh repo create your-project-name --private --source=. --remote=origin



# 推送代码到您的新项目仓库,并设置默认分支为 main

git push -u origin main

修改网站配色

选择一个 shadcn 主题调试器

在下面url中可以修改字体颜色等等

https://tweakcn.com/editor/theme

当前项目使用的是Claude主题:

https://ui.shadcn.com/themes

为你的项目调制一套主题配色:

Shipany 使用 tailwindcss4,请使用 oklch 颜色格式,复制主题样式

粘贴主题样式到项目文件:src/config/style/theme.css

重新进入项目预览页面,即可看到你定制的主题

配置环境变量


cp .env.example .env.development

修改环境变量值 (注意:登录、AI等配置不在这里,那些在管理后台页面,后面会有介绍)


# app

NEXT_PUBLIC_APP_URL = "http://localhost:3000"

NEXT_PUBLIC_APP_NAME = "Your App Name"



# theme

NEXT_PUBLIC_THEME = "default"



# appearance

NEXT_PUBLIC_APPEARANCE = "system"



# database

DATABASE_URL = ""

DATABASE_PROVIDER = "postgresql"

DB_SINGLETON_ENABLED = "true"



# auth secret

# 将 `openssl rand -base64 32` 复制粘贴到你的终端然后回车,就会生成一段值,复制粘贴到下面

AUTH_SECRET = ""

数据库

下图为Supabase获取DATABASE_URL值截图

注意:复制粘贴内容中[YOUR-PASSWORD] 是你要替换的内容,把[]要删除了,要不然连不上

例如

DATABASE_URL="postgresql://postgres.tsjbzbpzwilbxnrqkqzp:[YOUR-PASSWORD]@aws-0-us-west-1.pooler.supabase.com:6543/postgres"

如果本地开发你想用本地数据库

请点击项目本地开发时使用本地psql数据库, 在这个页面配置好后,再回到这里继续下面的操作

按照上面环境变量配置好后,迁移数据表

项目下终端运行下面命令:

第一步:

pnpm db:generate
第二步:

pnpm db:migrate

先把基础表弄起来,后面咱们再说怎么写入预制Showcase等数据

配置登录鉴权

管理后台RBAC初始化


pnpm rbac:init

注册管理员账户

访问 http://localhost:3000/admin 进入后台管理系统,由于没有登录会遇到登录拦截,重定向到 /sign-in 登录页面。

你需要先注册一个账户,比如 admin@xxx.com

分配超级管理员权限

注册成功后,在终端执行

admin@xxx.com 更换成你注册的账户邮箱


pnpm rbac:assign -- --email=admin@xxx.com --role=super_admin

访问管理后台

再次访问 http://localhost:3000/admin,即可进入管理后台。

配置google登录

访问https://console.cloud.google.com/apis/credentials

注意:如果没有Project的,先创建个Project!

下图为创建Project截图,要选择外部!

创建客户端

image

配置用到的(注意:生产环境的还得单独重新再配一个):

image

http://localhost:3000

http://localhost:3000/api/auth/callback/google

下图为生产配置时截图(仅供参考):

然后访问:http://localhost:3000/zh/admin/settings/auth

将google给你的复制粘贴到下图:

然后回到项目首页:http://localhost:3000

下图为第1种登录方式:OneTap生效
下图为第2中登录方式:Auth生效
google成功后跳回首页:
最后如果配完生产后是下面这样(2个)

github登录太简单了,就不写过程了,

我把官方文档放这里了,需要的自己点击去看下

Github 登录

字体图标使用

项目中使用了lucide-react、react-icons 中的 Remix Icon。如果有需要图标,可在这里查找

动态页面JSON配置

基础使用

设置通用展示内容

项目的通用展示内容,对应的配置文件是 src/config/locale/messages/{locale}/common.json

包括网站 metadata 信息,sign 登录注册文案,locale_detector 语言检测文案等。

你可以根据项目实际情况,按需修改配置文件内容。

其中 metadata 信息,是给搜索引擎收录的网站信息,在项目部署上线前,请一定要修改。

默认内容是:


{

  "metadata": {

    "title": "ShipAny Template Two",

    "description": "ShipAny is a NextJS boilerplate for building AI SaaS startups. Ship Fast with a variety of templates and components.",

    "keywords": "shipany, shipany-boilerplate, shipany-template-two-demo"

  }

}

你可以利用 AI 辅助生成配置文件内容,参考的提示词如下:


The project I am developing is an AI image generator based on Nano Banana Pro model,

please refer to the content on the webpage: https://gemini.google/overview/image-generation/,

help me modify the metadata information in the common configuration file under src/config/locale/messages/{locale}/common.json.

My project name is: Nano Banana Pro,

Keywords contains: nano banana pro, nano banana, nano banana 2, gemini 3 pro image.

设置着陆页内容

项目着陆页内容,对应的配置文件是 src/config/locale/messages/{locale}/landing.json

默认的配置内容,定义了着陆页 header / hero / features / testimonials / faq / cta 等区块的显示内容。你可以根据项目情况,部分或全部替换默认内容。

利用 AI 辅助生成配置文件内容,参考的提示词:


The project I am developing is an AI image generator based on Nano Banana Pro model,

please refer to the content on the webpage: https://gemini.google/overview/image-generation/,

help me modify the landing page content in the configuration file under src/config/locale/messages/{locale}/landing.json.

My project title is: Nano Banana Pro,

Keywords contains: nano banana pro, nano banana, nano banana 2, gemini 3 pro image.

自定义着陆页展示

自定义 Header
  • brand: 显示的品牌信息。包括 Logo、名称、跳转链接等。

  • nav: 显示的顶部导航菜单。

  • buttons:顶部右侧显示的按钮。

  • user_nav: 用户登录后点头像下拉显示的导航菜单。

  • show_sign: 是否显示登录注册按钮。

  • show_theme: 是否显示 light / dark 主题切换按钮。

  • show_locale: 是否显示语言切换按钮。


{

  "header": {

    "id": "header",

    "brand": {

      "title": "Nano Banana Pro",

      "logo": {

        "src": "/imgs/logos/banana.png",

        "alt": "Nano Banana Pro"

      },

      "url": "/"

    },

    "nav": {

      "items": [

        {

          "title": "Features",

          "url": "/#features",

          "icon": "Sparkles"

        }

      ]

    },

    "buttons": [

      {

        "title": "Quick Start",

        "url": "/docs/quick-start",

        "icon": "BookOpenText",

        "target": "_self",

        "variant": "outline"

      }

    ],

    "user_nav": {},

    "show_sign": false,

    "show_theme": false,

    "show_locale": false

  }

}

自定义区块


ShipAny 在 default 主题内置了以下区块:

hero:主区块

logos:Logo 列表区块

features:功能特点区块

features-list:特性列表区块

features-accordion:特性折叠区块

features-flow:特性流程区块

features-media:特性媒体区块

features-step:特性步骤区块

showcases:展示区块

showcases-flow:瀑布流区块

stats:统计数据区块

testimonials:用户评价区块

faq:常见问题区块

cta:行动号召区块

subscribe:订阅区块

landing如何配置增加上述区块,例如:showcases-flow:瀑布流区块

1、修改src/app/[locale]/(landing)/page.tsx


const showSections = [

    'hero',

    'showcases-flow', // 增加这一行

    'logos',

    'introduce',

    'benefits',

    'usage',

    'features',

    'stats',

    'testimonials',

    'subscribe',

    'faq',

    'cta',

  ];

2、修改src/config/locale/messages/en/landing.json, 不能复制粘贴,因为里面img的src你的项目不存在


"showcases-flow": {

    "id": "showcases-flow",

    "title": "Nano Banana Pro Showcases",

    "description": "Representative Nano Banana editing and generation cases powered by Nano Banana Pro",

    "items": [

      {

        "title": "AI SaaS Showcase 1",

        "description": "AI SaaS Showcase",

        "image": {

          "src": "/imgs/showcases/1.jpeg",

          "alt": "AI SaaS Showcase 1"

        }

      },

      {

        "title": "AI SaaS Showcase 2",

        "description": "AI SaaS Showcase",

        "image": {

          "src": "/imgs/showcases/2.jpeg",

          "alt": "AI SaaS Showcase 2"

        }

      },

      {

        "title": "AI SaaS Showcase 3",

        "description": "AI SaaS Showcase",

        "image": {

          "src": "/imgs/showcases/3.jpeg",

          "alt": "AI SaaS Showcase 3"

        }

      }

    ]

  }

landing如何配置某些块不显示

如果直接删除的话,就会报错:

此时:

1、修改src/app/[locale]/(landing)/page.tsx支持hidden参数


// build page sections

  const page: DynamicPage = {

    sections: showSections.reduce<Record<string, Section>>((acc, section) => {

      const sectionData = t.raw(section) as Section;

      // Skip sections that are explicitly hidden, null, or undefined

      if (

        sectionData &&

        typeof sectionData === 'object' &&

        sectionData.hidden !== true

      ) {

        acc[section] = sectionData;

      }

      return acc;

    }, {}),

  };

2、配置src/config/locale/messages/en/landing.json增加hidden参数

不想展示的块增配"hidden": true


"logos": {

    "hidden": true

  },

  "introduce": {

    "hidden": true

  },

  "benefits": {

    "hidden": true

  },

高阶使用

✨项目如何管理首页Showcases块、Showcases页、Hairstyles页数据

配置AI生图功能

先确定你的登录账户是admin角色

点击查看:✨项目中AI图片生成相关配置

Stripe支付

点击查看:✨项目中关于Stripe支付相关配置

Creem支付

点击查看:项目中关于Creem支付相关配置

部署

部署到 Vercel

点击查看:项目部署到Vercel

部署到Cloudflare

点击查看:项目部署到 Cloudflare Workers

部署到Dokploy

这个部署我没有用到,大家可以看部署到Dokploy-官方文档

Vercel和Cloudflare的区别:

|对比维度|Vercel|Cloudflare|

| ---- | ---- | ---- |

|核心定位|主打前端开发部署,聚焦开发者体验,是Next.js官方适配平台|定位“边缘操作系统”,以全球CDN和边缘计算为核心,兼顾部署与网络安全|

|框架适配|原生支持Next.js所有功能,包括实验性功能,适配无需额外配置|支持多语言框架,但对Next.js等框架需手动配置适配器,适配灵活性稍弱|

|免费额度|100次/天构建,100GB/月带宽,源文件大小限100MB|500次/月构建,带宽不限,D1数据库免费版限500MB存储|

|计算与存储|基于AWS Lambda的Serverless Functions,按流量计费,存储单独计费|Workers边缘计算(无冷启动),R2对象存储免费,云函数按请求次数计费|

|开发体验|集成度高,部署流程顺滑,Git提交自动构建预览,新手友好|配置稍复杂,免费版不支持并发构建,适合需控制细节的开发者|

|网络性能|国内访问时延较低,无需担心域名禁用等问题|全球节点多,但国内访问时延高,请求常回源至美国节点|

|特色功能|预览部署功能完善,适配Next.js的增量静态再生等专属能力|强大的DDoS防护、WAF等安全功能,支持Workers无缝拓展动态功能|

Cloudflare Workers 的费用分为免费计划、付费标准计划,企业账户则按合同约定计费,且付费计划还涵盖其关联的KV、Durable Objects等配套功能的收费规则,具体如下:

|计费项目|免费计划|付费标准计划|

| ---- | ---- | ---- |

|基础费用|0美元|每月最低5美元|

|核心请求量|每天10万次请求,每次调用含10毫秒CPU时间|每月包含1000万次请求,超出部分每100万次收费0.3美元;每月含3000万CPU毫秒,超出部分每1000万CPU毫秒收费0.02美元|

|Workers KV|每天10万次读请求,1000次写/删除请求,存储1GB|每月1000万次读请求、100万次写/删除请求,超出部分每100万次收费0.5美元;存储1GB,超出部分每1GB收费0.5美元|

|Durable Objects|不可用|每月包含100万次请求,超出部分每100万次收费0.15美元|

|队列操作|每月100万次操作|每月100万次操作,超出部分每100万次收费0.4美元|

|D1数据库|每天500万次读行、10万次写行,存储5GB|每月前25亿次读行、50万次写行,超出读行部分每100万次收费0.001美元,超出写行部分每100万次收费1美元;存储5GB|

|Workers Trace Events Logpush|不可用|每月1.1亿次请求量,超出部分每100万次收费0.05美元|

此外,企业账户的计费不遵循上述标准计划规则,而是依据合同中约定的使用模式计费,若需切换使用模式,需联系专属客户成功经理协调。

Vercel 付费分Pro和Enterprise两类计划,采用信用额度+按需计费结合的模式;Cloudflare 付费分Pro、Business、Enterprise三类固定套餐,还可额外选购增值服务,

预制数据

如果你不想你的网站部署成功后,很空,那么你可以导入我的预制数据

首页Showcase 预览

Showcase页 预览

Hairstyle页 预览

查看导入教程

✨项目可导入的表预制数据

On this page

初始化项目
通过shipany-template-nano-banana源码 去新建项目
下面命令是要部署在Vercel上的Clone项目命令
下面命令是要部署在Cloudflare上的Clone项目命令
安装依赖
启动开发服务器
点击输出的 Local 地址,在浏览器打开网页:http://localhost:3000 ,即可预览项目
如果你要将新项目提交到自己github仓库,需要做下面动作,上面的Clone会把源代码的.git远程仓库也Clone下来了,需要按照下面执行下命令,要不然你提交不上去
修改网站配色
选择一个 shadcn 主题调试器
在下面url中可以修改字体颜色等等
为你的项目调制一套主题配色:
粘贴主题样式到项目文件:src/config/style/theme.css
重新进入项目预览页面,即可看到你定制的主题
配置环境变量
修改环境变量值 (注意:登录、AI等配置不在这里,那些在管理后台页面,后面会有介绍)
数据库
下图为Supabase获取DATABASE_URL值截图
如果本地开发你想用本地数据库
按照上面环境变量配置好后,迁移数据表
项目下终端运行下面命令:
第一步:
第二步:
先把基础表弄起来,后面咱们再说怎么写入预制Showcase等数据
配置登录鉴权
管理后台RBAC初始化
注册管理员账户
分配超级管理员权限
访问管理后台
配置google登录
注意:如果没有Project的,先创建个Project!
下图为创建Project截图,要选择外部!
创建客户端
配置用到的(注意:生产环境的还得单独重新再配一个):
然后访问:http://localhost:3000/zh/admin/settings/auth
将google给你的复制粘贴到下图:
然后回到项目首页:http://localhost:3000
下图为第1种登录方式:OneTap生效
下图为第2中登录方式:Auth生效
google成功后跳回首页:
最后如果配完生产后是下面这样(2个)
github登录太简单了,就不写过程了,
字体图标使用
动态页面JSON配置
基础使用
设置通用展示内容
设置着陆页内容
自定义着陆页展示
自定义 Header
自定义区块
landing如何配置增加上述区块,例如:showcases-flow:瀑布流区块
1、修改src/app/[locale]/(landing)/page.tsx
2、修改src/config/locale/messages/en/landing.json, 不能复制粘贴,因为里面img的src你的项目不存在
landing如何配置某些块不显示
1、修改src/app/[locale]/(landing)/page.tsx支持hidden参数
2、配置src/config/locale/messages/en/landing.json增加hidden参数
高阶使用
配置AI生图功能
Stripe支付
Creem支付
部署
部署到 Vercel
部署到Cloudflare
部署到Dokploy
Vercel和Cloudflare的区别:
Cloudflare Workers 的费用分为免费计划、付费标准计划,企业账户则按合同约定计费,且付费计划还涵盖其关联的KV、Durable Objects等配套功能的收费规则,具体如下:
Vercel 付费分Pro和Enterprise两类计划,采用信用额度+按需计费结合的模式;Cloudflare 付费分Pro、Business、Enterprise三类固定套餐,还可额外选购增值服务,
预制数据
首页Showcase 预览
Showcase页 预览
Hairstyle页 预览
查看导入教程