掌握 Instatic：现代自托管视觉CMS

本章要解决的问题是如何快速部署 Instatic，让你在一分钟内启动自己的网站。读完这章后，你可以搭建一个基本的 Instatic 网站并进行简单的编辑。

前置条件：确保你已经安装了 Node.js 和 npm，并且熟悉基本的命令行操作。

第一步操作：创建一个新的项目目录并进入该目录。

mkdir my-instatic-site && cd my-instatic-site

这会创建一个名为 my-instatic-site 的新文件夹，并切换到该文件夹。

接着，初始化一个新的 npm 项目。

npm init -y

这条命令会生成一个默认的 package.json 文件。

然后，安装 Instatic。

npm install @instatic/core

这会下载并安装 Instatic 及其依赖项。

接下来，创建一个启动脚本。打开终端中的文本编辑器（如 VSCode），新建一个名为 index.js 的文件，并添加以下代码：

const { createServer } = require('@instatic/core');

createServer({
  port: 3000,
}).listen(() => {
  console.log('Instatic running at http://localhost:3000');
});

这段代码会创建一个监听端口 3000 的 Instatic 服务器。

最后，运行你的 Instatic 网站。

node index.js

执行这条命令后，在浏览器中访问 http://localhost:3000 即可看到你的 Instatic 网站已成功启动。

如果你遇到错误信息 "Cannot find module '@instatic/core'"，请检查是否正确安装了 Instatic。如果问题依旧，请确保 npm 安装无误并且网络连接正常。

一个小例子：假设你想为个人博客搭建一个简单的内容管理系统，通过上述步骤，你可以在本地快速搭建起一个支持可视化编辑的基本框架，之后可以进一步根据需求添加更多功能和样式定制。

本章小结

• 创建了一个新的项目目录并初始化了 npm 项目。
• 安装了 Instatic 并编写了一个简单的启动脚本。
• 成功启动了本地的 Instatic 网站，并了解了一些常见的错误排查方法。

本章要解决的问题是如何理解 Instatic 的架构，包括它的核心组件和工作原理。读完这章后，你会明白 Instatic 是如何整合所有功能在一个 Bun 服务器上的，并且知道它是如何生成干净的 HTML 和 CSS 的。

前置条件：你需要已经按照第一章的步骤成功启动了 Instatic 服务器，并且对 Node.js 和基本的 JavaScript 操作有一定了解。

我们先来看一下 Instatic 的整体架构图，虽然文档中没有提供具体的图片，但我们可以从描述中想象出来：

+-------------------+
|   Visual Editor   |
+---------+---------+
          |
          v
+-------------------+
| Content Management|
|       Engine      |
+---------+---------+
          |
          v
+-------------------+
|     Media & Auth  |
+---------+---------+
          |
          v
+-------------------+
|        Forms      |
+---------+---------+
          |
          v
+-------------------+
|    Plugin System  |
+---------+---------+
          |
          v
+-------------------+
|     Publisher     |
+-------------------+

         ^
         | 
         +-------> Output: Clean HTML/CSS

接着，我们来具体看看每个组件的作用：

1. 视觉编辑器 (Visual Editor)

// 这个部分主要通过前端界面让你能够拖拽、调整元素位置和样式。
// 我们不需要在这里写额外代码，只需知道它负责用户交互的部分。

这个组件允许你在浏览器中直观地设计网页布局和样式。

2. 内容管理引擎 (Content Management Engine)

// 负责存储和检索内容数据。
// 数据库可以选择 SQLite 或 Postgres。
const dbConfig = {
  type: 'sqlite', // 或者 'postgres'
  database: './data.db',
};

这个组件处理所有的内容操作，比如创建、更新和删除文章。

3. 媒体与认证 (Media & Auth)

// 处理媒体文件上传和用户认证逻辑。
const mediaConfig = {
  uploadDir: './uploads',
};

const authConfig = {
  secretKey: 'your-secret-key-here',
};

这里包括媒体文件管理和用户的登录注册功能。

4. 表单 (Forms)

// 提供表单构建和服务能力。
const formConfig = {
  submissionsDir: './form-submissions',
};

你可以在这个组件中创建各种表单，并收集用户提交的数据。

5. 插件系统 (Plugin System)

// 允许扩展 Instatic 功能。
const plugins = [
  require('@instatic/plugin-example'),
];

通过插件可以增加新特性或者修改现有行为。

6. 发布器 (Publisher)

// 将内容转换为静态 HTML 文件。
const publishOptions = {
  outputDir: './public',
};

发布器会将动态内容渲染成静态文件以便高效传输给客户端。

一个小例子：假设你要为公司网站添加一个新闻板块，可以通过视觉编辑器设计页面布局，使用内容管理引擎来撰写新闻稿，利用媒体与认证来管理图片资源以及限制访问权限。最后通过发布器生成静态页面提高加载速度。

本章小结

• 学习了 Instatic 的六大核心组件及其作用。
• 明白了各个组件之间的工作流程和相互关系。
• 知道了 Instatic 如何生成高效的静态 HTML 页面。

本章要解决如何使用 Instatic 的内置编辑器和设计系统来设计你的网站。完成本章后，你将能够通过可视化的界面创建和编辑网页，并且理解基本的设计系统概念。

前置条件：你需要已经成功部署了 Instatic 并且熟悉如何启动服务器。

我们先打开浏览器，进入 Instatic 的后台管理界面。

npm run dev

这行命令会启动本地开发服务器。打开浏览器访问 http://localhost:3000 进入管理界面。

接着，在左侧导航栏点击 "Design" 进入设计页面。你会看到一个空白的画布，这就是我们的设计区域。

如果你遇到 "无法连接到服务器" 的错误，请确保你在正确的目录下运行了 npm run dev 命令，并且没有防火墙阻止端口 3000。

我们先跑起来一个简单的页面布局。在右侧工具栏中找到 "Container" 模块并拖拽到画布上。然后在容器内继续添加 "Text" 和 "Image" 模块来丰富内容。

// 示例：在一个 Container 内添加 Text 和 Image
- Container
  - Text: 这是一个标题
  - Image: 图片URL地址

记住一点：所有的更改都会实时显示在画布上，方便预览效果。

接下来，我们尝试调整样式。选择任意一个模块，右侧会出现属性面板。在这里你可以设置颜色、字体大小、间距等样式属性。

如果发现某个属性不起作用，请检查是否正确选择了对应的模块，并确认输入值符合要求（例如颜色需要十六进制格式）。

一个小例子：假设我们要为公司网站制作首页，可以在 Container 中添加 Banner 图像、一段欢迎文本以及几个产品卡片。每个产品卡片可以用另一个 Container 来组合 Title、Description 和 Call-to-action Button 模块。

本章小结

• 学习了如何通过可视化编辑器创建和编辑网页。
• 掌握了如何使用不同的模块和组件来构建页面结构。
• 理解了如何通过属性面板调整模块样式。

本章要解决的问题是如何使用 Instatic 的模块、组件和模板来构建复杂的页面。完成之后，你将能够熟练地利用这些元素来搭建美观且功能丰富的网站。

请确保你在正确的目录下运行了 npm run dev 命令，并且没有防火墙阻止端口 3000。

我们先跑起来一个简单的页面布局。在右侧工具栏中找到 "Container" 模块并拖拽到画布上。然后在容器内继续添加 "Text" 和 "Image" 模块来丰富内容。

// 示例：在一个 Container 内添加 Text 和 Image
- Container
  - Text: 这是一个标题
  - Image: 图片URL地址

记住一点：所有的更改都会实时显示在画布上，方便预览效果。

接下来，我们尝试调整样式。选择任意一个模块，右侧会出现属性面板。在这里你可以设置颜色、字体大小、间距等样式属性。

如果发现某个属性不起作用，请检查是否正确选择了对应的模块，并确认输入值符合要求（例如颜色需要十六进制格式）。

现在我们引入组件的概念。假设我们要制作一个产品卡片，可以创建一个新的 Visual Component：

1. 点击左侧菜单中的 “Components” 标签。

2. 点击右上角的 "+ New Component" 按钮。

3. 输入组件名称如 "ProductCard" 并保存。

4. 在新打开的组件编辑界面中，我们可以自由组合多种模块来构建这个卡片：

   // 示例：构建 ProductCard 组件
   - Container (背景色:#f8f9fa)
     - Image (宽度:100%)
     - Text (标题): 产品名称
     - Text (描述): 产品描述信息
     - Button (调用动作): 查看详情

5. 完成后点击保存按钮，新的组件就创建好了。回到主页面后，可以直接从工具栏拖拽 "ProductCard" 组件到画布中使用了。

模板则用于定义整个网站的基本结构。比如我们可以创建一个包含头部和底部的标准模板：

1. 点击左侧菜单中的 “Templates” 标签。
2. 点击右上角的 "+ New Template" 按钮。
3. 输入模板名称如 "StandardTemplate" 并保存。
4. 在新打开的模板编辑界面中，我们可以设计出通用的部分：

   // 示例：构建 StandardTemplate 模板
   - Header (固定位置)
     - Logo (图片)
     - NavigationMenu (导航链接列表)
   - MainContentArea (主要内容区域)
     - Outlet (内容插入点)
   - Footer (页脚部分)
     - ContactInfo (联系方式)
     - SocialLinks (社交媒体链接)

5. 完成后点击保存按钮，新的模板就可以应用到所有基于它的页面上了。

一个小例子：假设我们要为一家电商网站制作商品分类页，在标准模板的基础上增加了一个产品循环展示区：

1. 创建一个新的页面并选择刚才制作的标准模板作为基础布局。
2. 在主内容区域内添加 Loop 模块：

   // 示例：添加 Loop 循环模块展示多个商品卡片
   - Loop(source:productsCollection, variantCount:2)
     Variant 1:
       ProductCard(productData:itemData)
     Variant 2:
       ProductCard(productData:itemData, style:{backgroundColor:'#e9ecef'})

3. 配置好数据源和其他属性后预览最终效果即可。

本章小结

• 学习了如何通过可视化编辑器创建和管理自定义组件及模板。
• 掌握了如何利用 Loop 模块实现动态内容展示。
• 理解了模块、组件与模板之间的层级关系及其应用场景。

处理数据：表单和数据库集成

本章教你如何在 Instatic 中设置和处理表单，并将其与数据库集成，以便收集用户输入的数据。

前置条件：

• 已经有一个运行中的 Instatic 实例。
• 对基本的 Instatic 页面和模块有一定了解。

第一步：配置数据库

首先确保你的 Instatic 实例已经连接到了合适的数据库（SQLite 或 Postgres）。

如果你还没有配置数据库，可以按照以下步骤来配置：

对于 SQLite：

docker-compose -f compose.prod.yml -f compose.sqlite.yml up -d

这个命令会启动一个带有 SQLite 数据库的 Instatic 实例。

对于 Postgres：

docker-compose -f compose.prod.yml -f compose.postgres.yml up -d

这个命令会启动一个带有 Postgres 数据库的 Instatic 实例。

第二步：创建表单

打开 Instatic 编辑器，进入你要添加表单的页面。点击“插入模块”，然后选择“Form”。

// 示例：添加 Form 模块
- Form(id:"contactForm", action:"/submit-form")
  Field(type:"text", label:"Name", name:"name")
  Field(type:"email", label:"Email", name:"email")
  Field(type:"textarea", label:"Message", name:"message")
  Button(label:"Submit")

这会在页面上添加一个包含姓名、邮箱和消息字段的基本联系人表单。

第三步：配置表单提交行为

为了使表单能够正确地将数据提交到数据库，你需要在服务器端进行一些配置。编辑 instatic.config.js 文件：

module.exports = {
  routes: [
    {
      path: '/submit-form',
      method: 'POST',
      handler: async (req, res) => {
        const { name, email, message } = req.body;
        await db.insert('form_submissions', { name, email, message });
        res.status(200).send({ success: true });
      },
    },
  ],
};

这段代码定义了一个 POST 请求处理器 /submit-form，用于接收并存储来自前端表单的数据。

第四步：测试表单功能

回到浏览器中的页面，填写并提交表单。你可以查看数据库中的 form_submissions 表是否成功插入了新记录。

如果遇到问题，请检查控制台日志是否有错误信息，并确认 db 连接正常以及路由配置无误。

一个小例子：假设我们要为一个博客网站添加评论功能，在文章详情页底部增加一个评论表单：

1. 创建一个新的页面或打开已有的文章详情页。
2. 在页面底部添加 Form 模块：

   // 示例：添加 Comment Form 模块
   - Form(id:"commentForm", action="/submit-comment")
     Field(type:"text", label:"Author Name", name:"authorName")
     Field(type:"textarea", label:"Comment", name:"commentText")
     Button(label:"Post Comment")

3. 配置服务器端路由处理评论提交：

   module.exports = {
     routes: [
       {
         path: '/submit-comment',
         method: 'POST',
         handler: async (req, res) => {
           const { authorName, commentText } = req.body;
           await db.insert('comments', { authorName, commentText });
           res.status(200).send({ success: true });
         },
       },
     ],
   };

这样就完成了一个简单的评论系统集成。

本章小结

• 学习了如何在 Instatic 中创建和配置表单模块。
• 掌握了如何将表单数据提交到服务器并存储到数据库中。
• 理解了如何通过自定义路由处理不同的请求类型。

本章要解决的问题是如何提升 Instatic 网站的性能，通过静态文件生成和缓存策略来加速加载速度。

上一章我们完成了评论系统的集成。现在我们需要确保我们的网站能够快速响应用户请求，无论是在首次访问还是后续访问时都能提供流畅的体验。

前置条件

• 已经安装并配置好了 Instatic。
• 确保你有一个可以用来测试性能的基本网站结构。

第一步操作：启用静态文件生成

直接在 instatic.config.js 文件中添加以下配置：

module.exports = {
  staticSiteGeneration: true,
};

这行代码启用了静态站点生成功能，Instatic 会在构建过程中生成所有页面的静态 HTML 文件。

第二步操作：设置缓存策略

编辑 nginx.conf 或你使用的反向代理服务器配置文件，添加如下缓存规则：

server {
    location / {
        expires max;
        add_header Cache-Control "public";
    }
}

这段配置告诉浏览器和 CDN 可以无限期地缓存这些资源，并且可以公开缓存它们。

第三步操作：压缩静态文件

使用 Gzip 来压缩传输给用户的静态文件。在 nginx.conf 中增加以下内容：

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

开启 Gzip 并指定哪些类型的文件应该被压缩，从而减少传输的数据量。

实用技巧与注意事项

• 如果你在开发环境中进行测试，请确保禁用缓存以便看到最新的更改。
• 不同类型的资源可能需要不同的缓存策略。例如，CSS 和 JavaScript 文件通常适合长期缓存，而动态内容则不适合。
• 使用工具如 Google PageSpeed Insights 来分析你的网站性能，并根据建议调整配置。

小例子

假设你的网站有一个博客部分，你可以为所有的文章页面启用静态文件生成，并且对这些页面设置长期缓存策略。这样当用户第一次访问某个文章页面时会稍慢一些因为需要从服务器获取数据并生成静态文件，但是之后再次访问或者不同用户访问都会非常快因为可以直接从缓存中获取已经生成好的 HTML 文件。

本章小结

• 启用了 Instatic 的静态站点生成功能。
• 配置了 Nginx 缓存策略以提高资源加载速度。
• 设置了 Gzip 压缩来减少传输数据量。

本章要教会你如何利用 Instatic 的插件系统来扩展网站的功能，让你能够添加自定义行为和集成第三方服务。通过本章的学习，你将能够创建和安装简单的插件。

在开始之前，请确保你已经完成了前几章的内容，特别是第 6 章中的性能优化配置，并且你的 Instatic 网站已经在本地或服务器上正常运行。

我们先从查看现有的插件开始：

cd path/to/instatic/plugins
ls

这行命令会列出所有已有的插件目录。

接着，我们尝试启用一个现有的插件。假设我们要启用 example-plugin：

cp -r example-plugin ../enabled-plugins/

这条命令将 example-plugin 目录复制到 enabled-plugins 文件夹中，从而激活该插件。

如果你遇到权限问题，可以使用 sudo 提升权限：

sudo cp -r example-plugin ../enabled-plugins/

记得重启 Instatic 服务器以应用更改：

docker-compose restart instatic-server

接下来，我们自己编写一个简单的插件。首先，在 plugins 目录下创建一个新的文件夹：

mkdir my-custom-plugin
cd my-custom-plugin

然后创建一个基本的插件配置文件 plugin.json：

{
  "name": "My Custom Plugin",
  "version": "1.0.0",
  "description": "This is a custom plugin for Instatic.",
  "author": "Your Name"
}

这个文件包含了插件的基本信息。

接着创建主脚本文件 index.js：

module.exports = function (app) {
  console.log('My Custom Plugin has been loaded!');
};

这段代码会在插件加载时打印一条消息到控制台。

最后，启用我们的新插件：

cp -r my-custom-plugin ../enabled-plugins/
docker-compose restart instatic-server

检查日志确认插件是否正确加载：

docker-compose logs instatic-server | grep 'My Custom Plugin'

你应该能看到类似 My Custom Plugin has been loaded! 的输出。

一个小例子：假设你想在用户提交表单后发送一封邮件通知管理员。你可以使用 NodeMailer 库来实现这一功能。首先安装 NodeMailer：

npm install nodemailer --save

然后修改 index.js 文件如下：

const nodemailer = require('nodemailer');

module.exports = function (app) {
  app.on('form.submitted', async (formData) => {
    let transporter = nodemailer.createTransport({
      service: 'gmail',
      auth: {
        user: 'your-email@gmail.com',
        pass: 'your-email-password'
      }
    });

    let mailOptions = {
      from: '"Instatic Form Submission" <your-email@gmail.com>',
      to: 'admin@example.com',
      subject: 'New Form Submission',
      text: JSON.stringify(formData)
    };

    await transporter.sendMail(mailOptions);
    console.log('Email sent:', formData);
  });
};

这段代码会在每次表单提交时触发，并向指定邮箱发送包含表单数据的邮件。

本章小结

• 学习了如何查看和启用现有的 Instatic 插件。
• 创建了一个简单的自定义插件并在 Instatic 中启用了它。
• 实现了一个监听表单提交事件并发送邮件通知的示例。

安装报错：如何解决“Cannot find module 'some-module'”？

在安装过程中遇到“Cannot find module 'some-module'”错误通常是由于缺少必要的Node.js模块。请确保你已经全局或本地安装了该模块。你可以通过以下命令尝试修复：

npm install some-module --save

如果问题仍然存在，请检查你的package.json文件以确认所有依赖项都已正确列出，并尝试重新运行npm install。

环境/依赖：是否需要特定版本的Node.js？

Instatic建议使用Node.js的LTS版本来避免兼容性问题。你可以通过以下命令检查当前使用的Node.js版本：

node -v

如果不匹配推荐版本，可以从Node.js官方网站下载并安装最新LTS版本。

配置：如何更改数据库设置为PostgreSQL？

要将Instatic从默认的SQLite切换到PostgreSQL，你需要修改配置文件中的数据库连接字符串。编辑.env文件，找到类似如下的行并进行调整：

DATABASE_URL=sqlite:///./dev.db

将其更改为指向你的PostgreSQL实例：

DATABASE_URL=postgresql://username:password@localhost:5432/mydatabase

然后重启Instatic服务以应用更改。

使用误区：为什么我的页面没有响应设计效果？

如果你发现页面在不同设备上显示不一致，可能是因为未启用响应式设计功能。确保你在编辑器中启用了多个断点视图，并根据不同的屏幕尺寸进行了适当的布局和样式调整。

此外，检查是否有任何CSS规则硬编码了宽度或其他属性，这可能会导致响应性失效。

与同类对比：相比其他CMS，Instatic有哪些独特优势？

与其他CMS相比，Instatic的独特之处在于其一体化的设计理念。它集成了视觉编辑器、内容引擎、发布者等多个功能于单一Bun服务器中，减少了开发过程中的复杂性和第三方工具的依赖。

具体来说：

• 自定义性强：内置Core Framework作为设计系统的核心组件。
• 性能优化：生成的静态HTML和紧凑CSS提升了加载速度。
• 易于部署：支持多种一键部署方式（如Railway、Render）以及Docker容器化部署。
• 无需框架运行时：减少前端代码体积，提高用户体验。

这些特性使得Instatic成为现代网站构建的理想选择。