xiaoju-survey 中文使用教程

一、项目速览

入门 · 1 分钟版

如果你正在寻找一套能直接部署、开箱即用的在线问卷/考试/测评系统，XIAOJUSURVEY（小桔调研）是一个值得关注的开源选项。它由滴滴出行内部孵化并开源，后端基于 NestJS + MongoDB，前端基于 Vue3 + ElementPlus，支持从问卷创建、发布、收集到数据分析的完整闭环。

一句话判断：如果你需要快速搭建一套面向企业或个人的调研系统，且不想从零写表单引擎和数据分析逻辑，这个项目可以直接拿来用。

核心看点：
- 40+ 种题型，100+ 模板，覆盖市场调研、考试、投票、满意度调查等场景
- 支持 AI 一句话生成问卷（对接 LLM）
- 提供跨端 SDK（React Native），可嵌入到 App 或 Web 中
- 内置分题统计、交叉分析等在线报表能力

作者视角：这个项目最让我意外的是它的「产品完整度」——不是那种只有 CRUD 的半成品，而是真的把问卷设计器、权限管理、数据导出、主题定制、安全审查等企业级功能都做好了。如果你之前用过 Typeform 或金数据，会发现它的设计思路很接近。

二、核心功能与架构

进阶 · 推荐细读

它是什么 → 它解决什么问题 → 谁最该用

问卷设计器：提供拖拽式可视化编辑器，支持显示逻辑、跳转逻辑、选项引用等动态规则。它解决的是「非技术用户也能创建复杂表单」的问题。最适合需要让运营/产品同学自行创建问卷的团队。

数据看板：自动生成分题统计、交叉分析图表，支持数据导出（CSV/Excel）。它解决的是「问卷回收后还要手动统计」的痛点。最适合需要快速出报告的市场调研或 HR 部门。

AI 生成问卷：输入一句话（如「生成一份员工满意度调查问卷」），系统自动生成完整问卷。它解决的是「从零设计问卷费时费力」的问题。最适合需要快速原型验证的场景。

权限与空间管理：支持多角色（管理员/编辑者/查看者）和空间隔离。它解决的是「多人协作时数据混乱」的问题。最适合企业级团队使用。

跨端 SDK：提供 React Native SDK，可将问卷嵌入到移动应用中。它解决的是「问卷需要在 App 内原生展示」的问题。最适合有移动端调研需求的团队。

架构概览

项目分为三个主要部分：

Server 端：NestJS 框架 + MongoDB 数据库，负责问卷的 CRUD、数据收集、权限验证、报表生成
Web 端：Vue3 + ElementPlus，包含管理后台（B 端）和问卷渲染（C 端）
跨端 SDK：React Native，用于在移动端原生渲染问卷

数据流大致是：用户通过 Web 设计器创建问卷 → 发布后生成链接/嵌入代码 → 受访者填写 → 数据回传到 MongoDB → 后台生成报表。

项目架构示意图

作者视角：如果你之前用过其他问卷系统（如 LimeSurvey 或 SurveyJS），会发现 XIAOJUSURVEY 的设计更「现代」——它把问卷结构抽象成了标准化的 Meta 协议，这意味着你可以通过修改协议来扩展题型，而不需要动前端渲染逻辑。对于开发者来说，二次开发成本确实低。

三、动手实践

入门

环境准备

你需要准备以下环境：
- Node.js >= 18（推荐 20 LTS）
- MongoDB >= 5.0（本地或远程均可）
- Git（可选，用于克隆仓库）

快速启动（本地开发模式）

第一步：克隆并安装依赖

git clone https://github.com/didi/xiaoju-survey.git
cd xiaoju-survey

# 安装 Server 端依赖
cd server
npm install

# 安装 Web 端依赖
cd ../web
npm install

第二步：启动 MongoDB

确保本地 MongoDB 服务正在运行。如果没有，可以用 Docker 快速启动：

docker run -d -p 27017:27017 --name mongo mongo:6

第三步：启动 Server

cd ../server
npm run local

默认启动在 http://localhost:7001，控制台会输出启动日志。

第四步：启动 Web

cd ../web
npm run serve

默认启动在 http://localhost:8080。

第五步：访问后台

打开浏览器访问 http://localhost:8080/management，你会看到登录页面。首次使用需要注册一个账号。

登录后，点击「新建问卷」→ 选择模板或从零开始 → 拖拽添加题型 → 发布 → 复制问卷链接给受访者。

最小可运行示例

创建一个简单的满意度调查问卷：

登录后台后，点击「新建问卷」
选择「空白问卷」
添加一个「单选题」：问题为「您对我们的服务满意吗？」，选项为「满意」「一般」「不满意」
添加一个「文本框」：问题为「有什么建议？」
点击「发布」
复制生成的链接（类似 http://localhost:8080/render/some-survey-id），在浏览器新标签页打开
填写并提交，回到后台查看数据

常见踩坑

坑 1：MongoDB 连接失败

如果你没有启动 MongoDB，Server 启动时会报错。可以用以下命令检查：

# 检查 MongoDB 是否运行
mongosh --eval "db.version()"

如果报错，先启动 MongoDB 再重试 Server。

坑 2：端口被占用

Server 默认 7001，Web 默认 8080。如果端口被占用，可以在 .env 文件中修改端口配置。

坑 3：跨域问题（开发环境）

Web 端默认会向 localhost:7001 发请求。如果你修改了 Server 端口，需要在 Web 端的 vue.config.js 中更新 proxy 配置。

四、进阶玩法

深入 · 老手可选

AI 生成问卷（对接 LLM）

项目内置了 AI 生成问卷的功能，但默认需要自己配置 LLM 接口。以 OpenAI 为例：

在 Server 的 .env 文件中添加以下配置：

AI_ENABLED=true
AI_PROVIDER=openai
AI_API_KEY=sk-your-openai-api-key
AI_MODEL=gpt-4

重启 Server，回到 Web 后台，点击「AI 生成」按钮
输入提示词，例如：「生成一份关于远程办公满意度的调查问卷，包含 10 个问题，涵盖工作环境、沟通效率、团队协作等方面」
系统会自动生成问卷并展示预览，你可以直接使用或修改

自定义题型

如果你想添加新的题型（比如「矩阵量表」），需要修改问卷 Meta 协议。项目将题型抽象为协议层，你只需要在 server/src/survey/schema 中添加新的题型定义，然后在 Web 端的 web/src/components/survey 中添加对应的渲染组件。

以添加一个简单的「滑块评分题」为例：

Server 端（新增 schema）：

// server/src/survey/schema/slider.schema.ts
export const SliderSchema = {
  type: 'slider',
  props: {
    min: { type: 'number', default: 0 },
    max: { type: 'number', default: 100 },
    step: { type: 'number', default: 1 },
    label: { type: 'string', default: '' },
  },
};

Web 端（新增渲染组件）：

<!-- web/src/components/survey/SliderQuestion.vue -->
<template>
  <div class="slider-question">
    <label>{{ question.props.label }}</label>
    <el-slider
      v-model="value"
      :min="question.props.min"
      :max="question.props.max"
      :step="question.props.step"
      show-input
    />
  </div>
</template>

<script setup>
import { ref } from 'vue';
const props = defineProps({ question: Object });
const value = ref(0);
</script>

数据推送集成

如果你需要将问卷数据实时推送到第三方系统（如 CRM 或数据仓库），可以配置自定义 Hook：

// server/src/hooks/data-push.hook.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class DataPushHook {
  async onSurveySubmit(surveyData: any) {
    // 将数据推送到外部 API
    await fetch('https://your-crm-api.com/survey-data', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(surveyData),
    });
  }
}

然后在 server/src/app.module.ts 中注册这个 Hook。

五、判断与建议