跳转到内容
StudioCMS 文档
主站点

快速入门指南

升级到最新版 StudioCMS 需要升级到最新版本？请查看这里！

开始前的准备工作

Section titled “开始前的准备工作”

使用 StudioCMS 需要满足以下条件：

准备数据库

Section titled “准备数据库”

StudioCMS 使用 @astrojs/db 连接您的 libSQL 数据库。您可以选择任何 libSQL 提供商或自托管 libSQL 服务器。

如果您使用 StudioCMS CLI，并且已安装 Turso CLI，可以跳过此步骤，直接使用 CLI 创建新数据库。

有关所需环境变量的详细信息，请参阅 @astrojs/db 数据库连接参数

使用 Turso 快速入门

Section titled “使用 Turso 快速入门”

  1. 安装 Turso CLI ^

  2. 登录或注册 ^ Turso 账号

  3. 创建新数据库

    Terminal window
    turso db create studiocms

  4. 获取并设置 ASTRO_DB_REMOTE_URL

    4a. 运行 show 命令查看数据库信息：

    Terminal window
    turso db show studiocms

    4b. 复制 URL 值并设置为 ASTRO_DB_REMOTE_URL：

    .env
    ASTRO_DB_REMOTE_URL=libsql://studiocms-yourname.turso.io

  5. 获取并设置 ASTRO_DB_APP_TOKEN

    5a. 创建新令牌用于数据库认证：

    Terminal window
    turso db tokens create studiocms

    5b. 复制命令输出并设置为 ASTRO_DB_APP_TOKEN：

    .env
    ASTRO_DB_APP_TOKEN=eyJhbGciOiJF...3ahJpTkKDw

现在可以继续设置您的 StudioCMS 项目了！

使用其他提供商或自托管 libSQL

Section titled “使用其他提供商或自托管 libSQL”

libSQL 同时支持 HTTP 和 WebSockets 作为远程服务器的传输协议，也支持本地文件或内存数据库。

有关所需环境变量的详细信息，请参阅数据库连接参数
了解所有 libSQL 选项（包括本地文件），请参阅 Astro 文档：远程 URL 配置选项^

创建 StudioCMS 项目

Section titled “创建 StudioCMS 项目”

  1. 使用 create 命令创建 StudioCMS 项目

    使用预置模板创建包含 StudioCMS 的 Astro 项目：

    Terminal window
    npm create studiocms@latest

    运行命令后，将提示您回答几个项目相关问题。完成后，CLI 将在指定目录创建新的 Astro 项目。

    随后系统会提示您完成后续步骤，包括确保环境变量正确设置以及运行项目完成安装。

  2. 运行 CLI 后，请确保 astro.config.mjs 文件正确配置：

    astro.config.mjs
    import { 
    function defineConfig<const TLocales extends Locales = never, const TDriver extends SessionDriverName = never, const TFontFamilies extends FontFamily[] = never>(config: AstroUserConfig<TLocales, TDriver, TFontFamilies>): AstroUserConfig<TLocales, TDriver, TFontFamilies>
    See the full Astro Configuration API Documentation
https://astro.build/config
    defineConfig     } from 'astro/config';
    import 
    function db(): AstroIntegration[]
    db     from '@astrojs/db';
    import 
    function node(userOptions: UserOptions): AstroIntegration
    node     from '@astrojs/node';
    import 
    const studioCMS: (options?: {
        sdk?: boolean | {
            cacheConfig?: boolean | {
                lifetime?: string | undefined;
            } | undefined;
        } | undefined;
        dbStartPage?: boolean | undefined;
        imageService?: {
            cdnPlugin?: "cloudinary-js" | undefined;
        } | undefined;
        defaultFrontEndConfig?: boolean | {
            htmlDefaultLanguage?: string | undefined;
            htmlDefaultHead?: {
                tag: "link" | "title" | "base" | "style" | "meta" | "script" | "noscript" | "template";
                attrs?: Record<string, string | boolean | undefined> | undefined;
                content?: string | undefined;
            }[] | undefined;
            favicon?: string | undefined;
            injectQuickActionsMenu?: boolean | undefined;
        } | undefined;
        dashboardConfig?: {
            dashboardEnabled?: boolean | undefined;
            inject404Route?: boolean | undefined;
            faviconURL?: string | undefined;
            dashboardRouteOverride?: string | undefined;
            AuthConfig?: {
                providers?: {
                    github?: boolean | undefined;
                    discord?: boolean | undefined;
                    google?: boolean | undefined;
                    auth0?: boolean | undefined;
                    usernameAndPassword?: boolean | undefined;
                    usernameAndPasswordConfig?: {
                        allowUserRegistration?: boolean | undefined;
                    } | undefined;
                } | undefined;
                enabled?: boolean | undefined;
            } | undefined;
            developerConfig?: {
                demoMode?: false | {
                    password: string;
                    username ...
    StudioCMS Integration
    

    A CMS built for Astro by the Astro Community for the Astro Community.
    @see ― The GitHub Repo: withstudiocms/studiocms for more information on how to contribute to StudioCMS.
    @see ― The StudioCMS Docs for more information on how to use StudioCMS.
    studioCMS     from 'studiocms';
    

    export default 
    defineConfig<never, never, never>(config: AstroUserConfig<never, never, never>): AstroUserConfig<never, never, never>
    See the full Astro Configuration API Documentation
https://astro.build/config
    defineConfig    ({
        
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never, TFontFamilies extends FontFamily[] = never>.site?: string
    @name ― site
    @type ― {string}
    @description 
    Your final, deployed URL. Astro uses this full URL to generate your sitemap and canonical URLs in your final build. It is strongly recommended that you set this configuration to get the most out of Astro.
    

    {
      site: 'https://www.my-site.dev'
    }
    site    : 'https://demo.studiocms.dev/',
        
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never, TFontFamilies extends FontFamily[] = never>.output?: "server" | "static"
    @name ― output
    @type ― {('static' | 'server')}
    @default ― 'static'
    @see ― adapter *
    @description 
    Specifies the output target for builds.
    

      

    • 'static' - Prerender all your pages by default, outputting a completely static site if none of your pages opt out of prerendering.
      • 

    • 'server' - Use server-side rendering (SSR) for all pages by default, always outputting a server-rendered site.
      • 

    

    import { defineConfig } from 'astro/config';
    

    export default defineConfig({
      output: 'static'
    })
    output    : 'server',
        
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never, TFontFamilies extends FontFamily[] = never>.adapter?: AstroIntegration
    @name ― adapter
    @see ― output *
    @description 
    Deploy to your favorite server, serverless, or edge host with build adapters. Import one of our first-party adapters for Netlify, Vercel, and more to engage Astro SSR.
    

    See our On-demand Rendering guide for more on SSR, and our deployment guides for a complete list of hosts.
    

    import netlify from '@astrojs/netlify';
    {
      // Example: Build for Netlify serverless deployment
      adapter: netlify(),
    }
    adapter    : 
    function node(userOptions: UserOptions): AstroIntegration
    node    ({ 
    UserOptions.mode: "standalone" | "middleware"
    Specifies the mode that the adapter builds to.
    

      

    • 'middleware' - Build to middleware, to be used within another Node.js server, such as Express.
      • 

    • 'standalone' - Build to a standalone server. The server starts up just by running the built script.
      • 

    mode    : "standalone" }),
        
    AstroUserConfig<TLocales extends Locales = never, TSession extends SessionDriverName = never, TFontFamilies extends FontFamily[] = never>.integrations?: (false | AstroIntegration | (false | AstroIntegration | null | undefined)[] | null | undefined)[]
    @name ― integrations
    @description 
    Extend Astro with custom integrations. Integrations are your one-stop-shop for adding framework support (like Solid.js), new features (like sitemaps), and new libraries (like Partytown).
    

    Read our Integrations Guide for help getting started with Astro Integrations.
    

    import react from '@astrojs/react';
    import mdx from '@astrojs/mdx';
    {
      // Example: Add React + MDX support to Astro
      integrations: [react(), mdx()]
    }
    integrations    : [
            
    function db(): AstroIntegration[]
    db    (),
            
    function studioCMS(options?: {
        sdk?: boolean | {
            cacheConfig?: boolean | {
                lifetime?: string | undefined;
            } | undefined;
        } | undefined;
        dbStartPage?: boolean | undefined;
        imageService?: {
            cdnPlugin?: "cloudinary-js" | undefined;
        } | undefined;
        defaultFrontEndConfig?: boolean | {
            htmlDefaultLanguage?: string | undefined;
            htmlDefaultHead?: {
                tag: "link" | "title" | "base" | "style" | "meta" | "script" | "noscript" | "template";
                attrs?: Record<string, string | boolean | undefined> | undefined;
                content?: string | undefined;
            }[] | undefined;
            favicon?: string | undefined;
            injectQuickActionsMenu?: boolean | undefined;
        } | undefined;
        dashboardConfig?: {
            dashboardEnabled?: boolean | undefined;
            inject404Route?: boolean | undefined;
            faviconURL?: string | undefined;
            dashboardRouteOverride?: string | undefined;
            AuthConfig?: {
                providers?: {
                    github?: boolean | undefined;
                    discord?: boolean | undefined;
                    google?: boolean | undefined;
                    auth0?: boolean | undefined;
                    usernameAndPassword?: boolean | undefined;
                    usernameAndPasswordConfig?: {
                        allowUserRegistration?: boolean | undefined;
                    } | undefined;
                } | undefined;
                enabled?: boolean | undefined;
            } | undefined;
            developerConfig?: {
                demoMode?: false | {
                    password: string;
                    username ...
    StudioCMS Integration
    

    A CMS built for Astro by the Astro Community for the Astro Community.
    @see ― The GitHub Repo: withstudiocms/studiocms for more information on how to contribute to StudioCMS.
    @see ― The StudioCMS Docs for more information on how to use StudioCMS.
    studioCMS    (),
        ],
    });

在配置 StudioCMS 时需特别注意：astro.config.mjs 文件中的 ​site 配置项是必需参数，必须设置为您的站点实际 URL 或临时占位 URL 才能确保系统正常运行。（例如：https://demo.studiocms.dev/ 或 http://localhost:4321/）

配置认证

Section titled “配置认证”

StudioCMS 认证需要至少在 .env 文件中设置加密密钥。

以下是 StudioCMS 认证所需的环境变量：

.env
# 用于用户名密码认证的加密密钥
CMS_ENCRYPTION_KEY="wqR+w...sRcg=="

使用以下命令生成安全加密密钥：

Terminal window
openssl rand --base64 16

并将输出设置为 CMS_ENCRYPTION_KEY 的值。

了解所有可用的认证环境变量，请参阅环境变量页面。

可选：配置 oAuth 认证

Section titled “可选：配置 oAuth 认证”

StudioCMS 支持 GitHub、Discord、Google 和 Auth0 的 oAuth 认证。要配置 oAuth，需要在 .env 文件中设置必需的环境变量，并确保在配置中启用了相应的提供商。

oAuth 提供商需要设置回调 URL（用户认证后的重定向路径）。

设置回调 URL

Section titled “设置回调 URL”

根据您的环境设置回调 URL：

环境回调 URL
生产环境https://your-domain.tld/studiocms_api/auth/<provider>/callback
测试开发http://localhost:4321/studiocms_api/auth/<provider>/callback

回调 URL 路径示例

Section titled “回调 URL 路径示例”

不同提供商对应的回调 URL 路径：

提供商回调 PATH
GitHub/studiocms_api/auth/github/callback
Discord/studiocms_api/auth/discord/callback
Google/studiocms_api/auth/google/callback
Auth0/studiocms_api/auth/auth0/callback

配置 package.json 脚本

Section titled “配置 package.json 脚本”

在 package.json 脚本中添加 --remote 参数：

package.json
{
    "name": "my-studiocms-project",
    "scripts": {
        "dev": "astro dev --remote",
        "build": "astro check & astro build --remote",
        "astro": "astro"
    }
}

运行 StudioCMS 项目

Section titled “运行 StudioCMS 项目”

得益于 Astro 的强大功能，StudioCMS 的运行非常简单。

首次设置（或数据表结构更新时）

Section titled “首次设置（或数据表结构更新时）”

在终端运行以下命令：

Terminal window
npx astro db push --remote
Terminal window
npm run dev --remote

运行命令后，您将看到项目在 localhost:4321 运行的消息。首次设置时，请访问 http://localhost:4321/start 完成 StudioCMS 配置。

本地 Astro 开发模式运行

Section titled “本地 Astro 开发模式运行”

在终端运行以下命令：

Terminal window
npm run dev --remote

运行后，访问 http://localhost:4321 查看您的项目。

恭喜！ 🥳 您已成功在 Astro 项目中安装 StudioCMS。

为 StudioCMS 添加前端

Section titled “为 StudioCMS 添加前端”

StudioCMS 是无头 CMS，您需要自行创建前端展示内容。如果需要预构建的前端，请查看包目录中的插件。

设置博客

Section titled “设置博客”

如需搭建博客，可以使用 @studiocms/blog 插件：

Terminal window
npm install @studiocms/blog

安装后，在 studiocms.config.mjs 文件中添加插件：

studiocms.config.mjs
import { 
function defineStudioCMSConfig(config: StudioCMSOptions): {
    sdk?: boolean | {
        cacheConfig?: boolean | {
            lifetime?: string | undefined;
        } | undefined;
    } | undefined;
    dbStartPage?: boolean | undefined;
    imageService?: {
        cdnPlugin?: "cloudinary-js" | undefined;
    } | undefined;
    defaultFrontEndConfig?: boolean | {
        htmlDefaultLanguage?: string | undefined;
        htmlDefaultHead?: {
            tag: "link" | "title" | "base" | "style" | "meta" | "script" | "noscript" | "template";
            attrs?: Record<string, string | boolean | undefined> | undefined;
            content?: string | undefined;
        }[] | undefined;
        favicon?: string | undefined;
        injectQuickActionsMenu?: boolean | undefined;
    } | undefined;
    dashboardConfig?: {
        dashboardEnabled?: boolean | undefined;
        inject404Route?: boolean | undefined;
        faviconURL?: string | undefined;
        dashboardRouteOverride?: string | undefined;
        AuthConfig?: {
            providers?: {
                github?: boolean | undefined;
                discord?: boolean | undefined;
                google?: boolean | undefined;
                auth0?: boolean | undefined;
                usernameAndPassword?: boolean | undefined;
                usernameAndPasswordConfig?: {
                    allowUserRegistration?: boolean | undefined;
                } | undefined;
            } | undefined;
            enabled?: boolean | undefined;
        } | undefined;
        developerConfig?: {
            demoMode?: false | {
                password: string ...
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.


StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.


Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms';


export default defineStudioCMSConfig({
 dbStartPage: true,
 contentRenderer: 'marked',
 verbose: true,
 dateLocale: 'en-us',
 // ...Other Options
})
defineStudioCMSConfig } from 'studiocms/config';
import 
function blog(options?: StudioCMSBlogOptions): StudioCMSPlugin
Creates and configures the StudioCMS Blog plugin.
@param ― options - Optional configuration options for the blog plugin.
@returns ― The configured StudioCMS plugin.
@example 
const blogPlugin = studioCMSBlogPlugin({
  blog: {
    title: 'My Blog',
    enableRSS: true,
    route: '/my-blog'
  },
  sitemap: true,
  injectRoutes: true
});
@param ― options.blog - Blog-specific options.
@param ― options.blog.title - The title of the blog. Defaults to 'Blog'.
@param ― options.blog.enableRSS - Whether to enable RSS feed. Defaults to true.
@param ― options.blog.route - The route for the blog. Defaults to '/blog'.
@param ― options.sitemap - Whether to trigger sitemap generation. Defaults to true.
@param ― options.injectRoutes - Whether to inject routes for the blog. Defaults to true.
blog from '@studiocms/blog';


export default 
function defineStudioCMSConfig(config: StudioCMSOptions): {
    sdk?: boolean | {
        cacheConfig?: boolean | {
            lifetime?: string | undefined;
        } | undefined;
    } | undefined;
    dbStartPage?: boolean | undefined;
    imageService?: {
        cdnPlugin?: "cloudinary-js" | undefined;
    } | undefined;
    defaultFrontEndConfig?: boolean | {
        htmlDefaultLanguage?: string | undefined;
        htmlDefaultHead?: {
            tag: "link" | "title" | "base" | "style" | "meta" | "script" | "noscript" | "template";
            attrs?: Record<string, string | boolean | undefined> | undefined;
            content?: string | undefined;
        }[] | undefined;
        favicon?: string | undefined;
        injectQuickActionsMenu?: boolean | undefined;
    } | undefined;
    dashboardConfig?: {
        dashboardEnabled?: boolean | undefined;
        inject404Route?: boolean | undefined;
        faviconURL?: string | undefined;
        dashboardRouteOverride?: string | undefined;
        AuthConfig?: {
            providers?: {
                github?: boolean | undefined;
                discord?: boolean | undefined;
                google?: boolean | undefined;
                auth0?: boolean | undefined;
                usernameAndPassword?: boolean | undefined;
                usernameAndPasswordConfig?: {
                    allowUserRegistration?: boolean | undefined;
                } | undefined;
            } | undefined;
            enabled?: boolean | undefined;
        } | undefined;
        developerConfig?: {
            demoMode?: false | {
                password: string ...
A utility function to define the StudioCMS config object.
This function is used to define the optional StudioCMS
config object in the Astro project root. The expected file
name is studiocms.config.mjs. And it should be adjacent
to the Astro project's astro.config.mjs file.


StudioCMS will attempt to import this file and use the default
export as the StudioCMS config object automatically if it exists.


Using this function is optional, but it can be useful for IDEs
to provide better intellisense and type checking.
@example 
// studiocms.config.mjs
import { defineStudioCMSConfig } from 'studiocms';


export default defineStudioCMSConfig({
 dbStartPage: true,
 contentRenderer: 'marked',
 verbose: true,
 dateLocale: 'en-us',
 // ...Other Options
})
defineStudioCMSConfig({
    
dbStartPage?: boolean | undefined
dbStartPage: false,
    
plugins?: StudioCMSPlugin[] | undefined
plugins: [
        
function blog(options?: StudioCMSBlogOptions): StudioCMSPlugin
Creates and configures the StudioCMS Blog plugin.
@param ― options - Optional configuration options for the blog plugin.
@returns ― The configured StudioCMS plugin.
@example 
const blogPlugin = studioCMSBlogPlugin({
  blog: {
    title: 'My Blog',
    enableRSS: true,
    route: '/my-blog'
  },
  sitemap: true,
  injectRoutes: true
});
@param ― options.blog - Blog-specific options.
@param ― options.blog.title - The title of the blog. Defaults to 'Blog'.
@param ― options.blog.enableRSS - Whether to enable RSS feed. Defaults to true.
@param ― options.blog.route - The route for the blog. Defaults to '/blog'.
@param ― options.sitemap - Whether to trigger sitemap generation. Defaults to true.
@param ― options.injectRoutes - Whether to inject routes for the blog. Defaults to true.
blog(),
    ],
});

构建和部署 StudioCMS 项目

Section titled “构建和部署 StudioCMS 项目”

完成首次设置后，即可构建并部署项目到服务器。

默认情况下，StudioCMS 仪表板位于 http://your-domain.tld/dashboard。

该仪表板可用于在开发和生产环境中管理内容和设置。

建议：在生产模式下使用 StudioCMS，开发模式下仪表板可能出现问题（如 Vite 依赖错误）。

后续步骤

Section titled “后续步骤”

了解如何设置 StudioCMS 的环境变量。

查看包目录，寻找和使用 StudioCMS 插件。

通过 StudioCMS 参考文档 了解配置选项。