入门
快速开始
第一次使用？先看 5 分钟上手：生成站点、安装、加插件、部署到 Cloudflare。本页是环境要求、框架开发与升级的参考。
环境要求
| 依赖 | 版本 |
|---|---|
| Node.js | 22 或更高 |
| pnpm | 10（仓库已通过 pnpm-workspace.yaml 固定存储参数） |
| 数据库 | 默认无需安装，使用 SQLite 文件；可选 PostgreSQL 14+ / MySQL 8.0.13+ / MariaDB 10.2+ |
一条命令创建站点
npx -y https://insightme.top/create-nuxtcms.tgz my-site --template corporate
cd my-site && pnpm install && pnpm dev
模板与参数见 模板。下面是开发框架本身的步骤。
安装
git clone https://github.com/guxingbiao0507/nuxtcms.git
cd nuxtcms
pnpm install
cp .env.example .env
.env 中至少设置：
NUXT_JWT_SECRET=<随机 32 位以上字符串> # openssl rand -base64 32
NUXT_SESSION_PASSWORD=<随机 32 位以上字符串>
DATABASE_URL=file:.data/cms.sqlite
启动
pnpm dev
打开 http://localhost:3000，会跳转到默认语言首页 /zh。首次访问 /zh/setup 完成安装：
- 填写站点名称、描述、管理员账号。
- 勾选 导入演示内容（默认勾选）会写入一套中英双语的科技公司示例：3 个产品分类、6 个产品、2 个文章分类、6 篇文章和一个「关于我们」页面。
- 安装完成后自动登录并进入后台
/zh/admin。
开发环境启动时会自动执行数据库迁移；演示内容也可以随时用 pnpm seed:demo 写入空库。
目录结构
app/ 前台页面、布局、组件（站点项目通常覆盖这里）
pages/admin/ 后台页面
server/api/ 接口：public（前台）、admin（后台）、auth、setup
server/database/ Drizzle schema、方言适配器、迁移、演示数据
server/utils/ 认证、缓存、存储、SEO、邮件等工具
server/routes/ robots.txt、sitemap.xml、llms.txt
i18n/ 语言配置与翻译文件
deploy/ PM2、nginx、Dockerfile、wrangler 样例
docs/ 中英文文档
作为站点基座使用
站点项目把本仓库作为 Nuxt Layer 引用，然后只覆盖需要定制的文件：
// 站点的 nuxt.config.ts
export default defineNuxtConfig({
extends: ['nuxtcms'],
})
// 站点的 package.json
{ "dependencies": { "nuxtcms": "github:guxingbiao0507/nuxtcms#v1.3.2" } }
建议锁定 tag，基座升级时再手动提升版本。
站点样式 main.css
基座注册的样式入口是 ~/assets/css/main.css，在站点里它解析为站点自己的 app/assets/css/main.css，所以站点的 main.css 要包含基座需要的内容。基座的后台页面和官方插件（shop、blog）位于 node_modules，Tailwind 默认不扫描，需要用 @source 指过去（upgrade.mjs 会自动补上缺的行）：
@import "tailwindcss";
@import "@nuxt/ui";
@source "../../../node_modules/nuxtcms/app";
@source "../../../node_modules/nuxtcms/plugins";
@custom-variant dark (&:where(.dark, .dark *));
升级步骤
一条命令（推荐）：
node node_modules/nuxtcms/scripts/upgrade.mjs --deploy # 最新版本：安装、D1 迁移、构建、部署、健康检查
后台仪表盘在有新版本时会提示并给出这条命令。手动升级：
- 改
package.json里的 tag，pnpm install。 - 看 更新日志 的 Upgrade 段，把新增的 SQLite 迁移（都可重复执行）应用到 D1：
wrangler d1 migrations apply <db> --remote；自定义表前缀的站点直接执行替换前缀后的 SQL。 pnpm build:cf通过后提交、部署。
用 nuxtcms doctor 体检站点
npx nuxtcms doctor（或 node node_modules/nuxtcms/scripts/doctor.mjs）会列出站点覆盖了哪些基座文件、每份副本缺了什么（插件插槽、历史版本、新版本提示、后台菜单等）。多数缺口一行就能补上：app.vue 里加 <CmsAppEnd />，自定义仪表盘加 <AdminUpdateBanner />，自定义编辑器加 <ContentRevisions />，自定义后台布局用 useAdminNavExtras()。与基座完全相同的副本可以直接删除。
常用命令
| 命令 | 说明 |
|---|---|
pnpm dev | 开发服务器 |
pnpm build:node / pnpm start | Node 生产构建与启动 |
pnpm build:pages / pnpm deploy | Cloudflare Pages 构建与发布 |
pnpm lint / pnpm typecheck | 代码检查 |
pnpm db:generate / db:migrate | 生成 / 执行迁移（:pg、:mysql 后缀对应其他数据库） |
pnpm db:check-parity | 校验三套 schema 一致 |
pnpm db:smoke:pg | 用内嵌 PGlite 验证 PostgreSQL 方言 |
pnpm db:diff:sqlite | 对比 SQLite 库与 schema 快照的差异 |
pnpm seed:demo | 写入演示内容 |