项目位置:
https://github.com/openstarter-dev/openstarter
一、安装步骤
下面是基于原生 Windows 环境的具体操作步骤,你可以打开 PowerShell,在项目根目录下依次执行。
⚙️ 第一步:确认并配置核心环境
在安装依赖前,请先确保 Node.js 和包管理器 pnpm 的版本符合要求。
-
检查 Node.js 版本:OpenStarter 要求 Node.js 24.x。你可以在 PowerShell 中输入
node -v来确认版本。如果版本不符,建议先安装或切换到 Node 24。 -
启用 pnpm:OpenStarter 通过
packageManager字段锁定了 pnpm 版本,推荐使用 Corepack 来自动管理。在 PowerShell 中执行:corepack enable
执行后,Corepack 会自动根据项目配置使用正确的 pnpm 版本。
📦 第二步:安装项目依赖
环境就绪后,在项目根目录运行安装命令。由于涉及原生模块编译,首次安装可能耗时较长,请耐心等待。
pnpm install
小提示:如果安装过程非常慢或卡住,可能是 Windows Defender 实时扫描导致的。可以考虑将 pnpm 的存储路径加入 Defender 排除列表来提速。
🔑 第三步:配置环境变量
项目需要一些本地环境变量才能运行,最核心的是用于加密会话的密钥。
-
创建
.env文件:在项目根目录下,找到.env.example文件,将其复制一份并重命名为.env。copy .env.example .env
-
生成并填入密钥:
.env文件中的BETTER_AUTH_SECRET是必填项。你可以在 PowerShell 中运行以下命令来生成一个随机密钥:# 方法一:使用 OpenSSL (如果已安装) openssl rand -base64 32 # 方法二:使用 Node.js (如果 OpenSSL 不可用) node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
将生成的字符串复制,粘贴到
.env文件中BETTER_AUTH_SECRET=的后面。通常还需要确认BETTER_AUTH_URL为http://localhost:3000。
🗄️ 第四步:初始化本地数据库
OpenStarter 默认使用本地 SQLite,无需额外安装数据库软件。运行迁移命令来创建数据表结构:
pnpm db:migrate
这个命令会应用项目预设的数据库迁移文件。
备注:
这一步老是出错,出现的问题包括:
1.wrangler 确实已经是 apps/web 的依赖("wrangler": "^4.162.0"),但你在根目录运行 pnpm wrangler 依然会失败。这不是安装问题,而是 pnpm 的隔离式依赖管理机制导致的。
2.apps/web 目录下只有 wrangler.example.jsonc,没有正式的 wrangler.jsonc。Wrangler 只认 wrangler.jsonc 或 wrangler.toml,所以它报“No configuration file found”。你只需要把示例文件复制成正式配置即可
🚀 第五步:启动开发服务器
完成以上所有步骤后,就可以启动项目了:
pnpm dev
命令执行后,终端通常会提示服务已启动。你可以在浏览器中访问 http://localhost:3000 来查看你的 OpenStarter 应用。
备注:同时启动6个项目报错,后来单独启动web成功。
核心原因在于 OpenStarter 的 dev 脚本试图同时启动全部 6 个应用,而其中至少有一个(桌面端 desktop)的启动脚本在 Windows 上会触发 spawn EINVAL 错误,导致 Turborepo 判定整体失败并中止了其他应用的启动
三、安装成功
