项目快速上手图文教程
初始化项目
通过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主题:
为你的项目调制一套主题配色:
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截图,要选择外部!
创建客户端
配置用到的(注意:生产环境的还得单独重新再配一个):
下图为生产配置时截图(仅供参考):
然后访问:http://localhost:3000/zh/admin/settings/auth
将google给你的复制粘贴到下图:
然后回到项目首页:http://localhost:3000
下图为第1种登录方式:OneTap生效
下图为第2中登录方式:Auth生效
google成功后跳回首页:
最后如果配完生产后是下面这样(2个)
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
部署到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页 预览