跳到主要内容
版本：3.0

初始化项目

学习目标
  • 准备 Node.js 开发环境 (v22)。
  • 使用脚手架 (create-steedos-app) 初始化项目。
  • 核心技能：理解基于 Workspaces 的项目目录结构。
  • 核心技能：掌握使用 Yarn 脚本启动数据库和服务的流程。

Steedos 3.0 采用标准的 Node.js 微服务架构，项目结构清晰，内置了完整的运行环境。

1. 基础环境准备 (Prerequisites)​

在开始之前，请确保你的电脑（Windows/Mac/Linux）已安装以下软件：

Node.js & Yarn​

Steedos 依赖 Node.js 运行。

  • Node.js: 推荐版本 v22 LTS。
  • Yarn: 项目依赖 Yarn Workspaces 管理多软件包，必须安装 Yarn。 
    npm install -g yarn

数据库服务 (Docker)​

Steedos 需要 MongoDB 存储数据，Redis 存储缓存。 您可以在本机直接安装这些数据库软件，或者使用 Docker 运行它们。

2. 开发工具 (VS Code)​

Visual Studio Code 是开发 Steedos 项目的最佳伴侣。

推荐插件​

为了获得最佳的开发体验（语法高亮、代码补全），建议安装：

  1. ESLint & Prettier: 保证代码格式规范。
  2. Steedos Extensions: (官方插件) 提供元数据代码补全和可视化同步功能。

3. 初始化项目 (Scaffolding)​

我们提供了一个脚手架工具，只需一行命令即可生成标准的工程目录。

第一步：创建项目​

打开终端，运行以下命令：

npx create-steedos-app my-steedos-project

第二步：安装依赖​

进入项目目录并安装依赖包。由于使用了 Workspaces，这一步会同时安装主项目和所有子软件包的依赖。

cd my-steedos-project
yarn install

4. 目录结构详解 (Anatomy)​

生成的项目是一个 Monorepo (单体仓库) 结构，核心逻辑位于 steedos-packages 目录下：

my-steedos-project/
├── .vscode/               # VS Code 推荐配置
├── steedos-packages/      # [核心] 工作区目录，存放所有的业务软件包
│   └── example-app/       # 示例业务包 (你可以复制它创建新包)
│       ├── package.json   # 定义包名和依赖
│       └── main/
│           └── default/
│               ├── objects/   # 对象定义 (.object.yml)
│               ├── triggers/  # 后端触发器代码 (.js)
│               └── apps/      # 应用菜单定义 (.app.yml)
├── services/              # 微服务配置 (moleculer.config.js)
├── steedos-config.yml     # 系统主配置文件 (数据库链接、端口等)
├── package.json           # 项目主文件，定义了启动脚本
├── docker-compose.yml     # 数据库编排文件
└── .gitignore
开发指南

你的代码应该写在哪里？ 请在 steedos-packages/ 目录下工作。

  • Steedos 启动时会自动扫描该目录下所有声明为 steedos-package 的子文件夹。
  • 你可以在这里创建多个文件夹（如 finance-pkg, hr-pkg）来隔离不同的业务模块。

5. 启动开发服务 (Run & Debug)​

我们在 package.json 中内置了快捷命令，你不需要记忆复杂的 Docker 指令。

第一步：启动数据库​

项目内置了 start:db 脚本，它会自动调用 Docker Compose 启动 MongoDB 和 Redis。

yarn start:db

(注意：请确保 Docker Desktop 已启动。此命令会占用本机的 27017 和 6379 端口)

第二步：启动 Steedos 服务​

运行以下命令启动主程序（基于 @steedos/server）：

yarn start

当终端看到以下日志时，说明启动成功：

🚀 Application is running on: http://localhost:5100

第三步：访问系统​

打开浏览器访问：

http://localhost:5100

(注：默认端口通常为 5100，具体请以控制台打印的日志为准。)

6. 版本控制 (Git)​

应该提交什么？(Commit)​

  • steedos-packages/ 下的所有业务代码 (.yml, .js)。
  • package.json 和 yarn.lock。

不应该提交什么？(Ignore)​

  • node_modules/
  • .steedos/ (系统运行时生成的临时缓存，绝对不要提交)
  • steedos-storage/ (本地上传的附件)

常见问题 (FAQ)​

Q: yarn install 报错？ A: 请检查 Node.js 版本是否为 v18 或 v22。

Q: yarn start:db 没反应？ A: 请确认 Docker Desktop 是否正在运行。你也可以手动执行 docker-compose up -d 来排查详细错误。

Q: 为什么我修改了 package.json 里的依赖，代码里引用不到？ A: 在 Workspaces 模式下，如果你是在 steedos-packages/my-app 里使用依赖，建议进入该目录执行 yarn add xxx，或者在根目录使用 yarn workspace @my-app/name add xxx。

微信扫码