快速开始

在开始使用 ShipAny 之前，请确保你已经获取 ShipAny 并已获得 ShipAny Two 代码仓库访问权限。

本地开发

初始化项目

拉取 ShipAny Two 源代码

git clone git@github.com:shipanyai/shipany-template-two my-shipany-project

默认拉取的是 dev 分支的代码，基于 Next.js 16，可部署在 Vercel，或通过 VPS + Dokploy 部署。

dev 分支是开发分支，更新迭代快，包含最新的功能特性。如果你追求版本稳定性，可以选择拉取 main 分支的代码。

git clone -b main git@github.com:shipanyai/shipany-template-two my-shipany-project

如果你需要部署在 Cloudflare Workers，请拉取 cf 分支的代码，此分支基于 Next.js 15.5.5，暂不支持 Next.js 16。

git clone -b cf git@github.com:shipanyai/shipany-template-two my-shipany-project

拉取完代码之后，进入项目根目录，后续的命令行操作都在项目根目录下执行。

cd my-shipany-project

安装依赖

执行以下命令，安装项目依赖。

pnpm install

启动开发服务器

执行以下命令，启动开发服务器。

pnpm dev

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

启动的开发服务器默认监听 3000 端口，如果你希望使用其他端口，可以在启动开发服务器时指定端口。

pnpm dev --port 8080

新的项目预览地址就是：http://localhost:8080。

预览项目

打开项目预览地址，首次看到的页面是这样的：

配置环境变量

创建配置文件

通过下面的命令，复制一份配置文件，用于配置本地开发用到的环境变量。

cp .env.example .env.development

修改环境变量值

根据你的项目信息，自行修改配置文件中的内容。

# app
NEXT_PUBLIC_APP_URL = "http://localhost:3000"
NEXT_PUBLIC_APP_NAME = "ShipAny Two"

# 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 = ""

必填项：

NEXT_PUBLIC_APP_URL：项目主页地址。复制项目预览地址填入
NEXT_PUBLIC_APP_NAME：应用名称。改成你的项目名称

选填项：

NEXT_PUBLIC_THEME：项目主题。默认是 default，对应的主题文件夹是： src/themes/default。如果你有自定义主题的需求，可以修改此选项。
NEXT_PUBLIC_APPEARANCE：项目外观。默认是 system，会根据用户电脑设置的系统主题自动切换。你可以改成 light 或 dark，来控制项目默认显示的外观。
DATABASE_URL：数据库连接地址。如果你需要用户登录、管理后台等功能，需要配置此项。
DATABASE_PROVIDER：数据库提供商。目前仅支持 postgresql。支持 Supabase, Neon 等云数据库和自建的 PostgreSQL 数据库。
DB_SINGLETON_ENABLED：数据库单例模式。默认是 true，会复用数据库连接。如果部署在 Cloudflare Workers 等 Serverless 平台，需要改为 false。
AUTH_SECRET：鉴权密钥。如果要开启用户登录功能，需要配置此项。

可以通过以下命令生成随机密钥：

openssl rand -base64 32

配置数据库

如果你的项目需要用户登录、管理后台等功能，必须按照以下步骤配置数据库。

创建数据库

你可以在 Supabase、Neon 等云数据库平台创建数据库，得到云数据库的远程连接地址，类似这种：

postgresql://postgres.xxx:xxxxxx@aws-0-ap-southeast-1.pooler.supabase.com:6543/postgres

你也可以使用自建的 PostgreSQL 数据库，得到数据库的连接地址，类似这种：

postgresql://user:password@127.0.0.1:5432/my_shipany_project

建议本地开发使用自建的 PostgreSQL 数据库，线上版本使用云数据库。

常用数据库的创建和连接地址获取，可以参考：数据库部分的文档。

设置环境变量

把上一步骤得到的数据库连接地址填入环境变量 DATABASE_URL。

DATABASE_URL = "postgresql://user:password@127.0.0.1:5432/my_shipany_project"
DATABASE_PROVIDER = "postgresql"
DB_SINGLETON_ENABLED = "true"

迁移数据表

执行以下命令，迁移数据表

pnpm db:generate
pnpm db:migrate

迁移数据表命令，在连接数据库时，读取的是 .env.development 文件中的 DATABASE_URL 变量。

如果在执行迁移命令：pnpm db:migrate 时遇到 Timeout 超时问题，或者长时间无响应。你需要通过以下命令检查你的数据库能否被正常连接。

psql "postgresql://user:password@address:port/database" # YOUR-DATABASE-URL

如果通过命令直接连接数据库也无法连上，你需要检查你的数据库地址是否有误，或者是否存在网络问题（比如防火墙、代理等）。

正常执行 pnpm db:migrate 迁移数据表成功后，你可以再次执行上述命令，验证数据表是否成功创建。

你可以在本地开发时，把 DATABASE_URL 设置成本地数据库地址。部署上线前，把 DATABASE_URL 设置成线上数据库地址，执行完迁移数据表命令，再改回本地数据库地址。

在 .env.development 文件中，通过注释来切换数据库地址。

# local database
DATABASE_URL = "postgresql://user:password@127.0.0.1:5432/my_shipany_project"

# remote database
# DATABASE_URL = "postgresql://postgres.xxx:xxxxxx@aws-0-ap-southeast-1.pooler.supabase.com:6543/postgres"

DATABASE_PROVIDER = "postgresql"
DB_SINGLETON_ENABLED = "true"

配置登录鉴权

ShipAny 使用了 Better Auth 实现用户登录鉴权功能。

如果你的网站只使用 Landing Page 实现静态网站功能，可以不配置登录鉴权。

如果你的网站需要用户登录、支付、管理后台等功能，必须配置登录鉴权。

生成鉴权密钥

通过以下命令生成随机的鉴权密钥。

openssl rand -base64 32

设置环境变量

把上一步骤生成的鉴权密钥填入 .env.development 文件中的 AUTH_SECRET 变量。

AUTH_SECRET = "your-secret-key"

配置了 AUTH_SECRET 后，默认开启邮箱登录，用户访问你的网站时，会请求 /api/auth/get-session 接口检查登录状态。未配置 AUTH_SECRET 时，不会检查登录状态。

配置管理后台访问

ShipAny 内置了后台管理系统和基于权限的访问控制（RBAC），你需要先完成上面的配置数据库和配置登录鉴权步骤，再按照下面的步骤配置管理后台访问。

初始化权限

执行以下命令，初始化权限配置。

pnpm rbac:init

此步骤会往数据库写入默认的角色和权限列表，连接的是 .env.development 文件中 DATABASE_URL 对应的数据库。

如果连接的是远程数据库，此步骤可能会遇到 Timeout 超时问题，重试即可。

可以配置 DB_SINGLETON_ENABLED = "true"，启用数据库单例模式，复用连接，提升初始化速度。

注册管理员账户

访问 http://your-domain/admin 进入后台管理系统，第一次会遇到登录拦截，重定向到 /sign-in 登录页面。你需要先通过邮箱注册一个管理员账户，比如 admin@xxx.com

分配超级管理员权限

执行以下命令，给新注册的账户分配超级管理员权限

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

访问管理后台

再次访问 http://your-domain/admin，使用管理员账户登录，即可进入管理后台。