第2章：环境搭建 —— 安装、Hello World 与本地开发仪表盘

encore run 一条命令能给你的远不止一个 HTTP 服务。本章把安装、项目结构、本地仪表盘和 daemon 机制一次讲透，包括 Windows 中文用户名环境的实测坑。

一、前置条件

• Node.js 18+（建议 20+；Bun 也受支持）
• Docker：本地开发时 Encore 用它自动拉起 Postgres / NSQ 容器。不用数据库和 Pub/Sub 的纯 API 应用可以不装，但强烈建议装上。
• Git（encore app create 会初始化仓库）

二、安装 CLI

# macOS
brew install encoredev/tap/encore

# Linux
curl -L https://encore.dev/install.sh | bash

# Windows (PowerShell)
iwr https://encore.dev/install.ps1 | iex

验证与升级：

encore version          # 当前版本（本教程基准 v1.57+，2026-08 最新 v1.58.x）
encore version update   # 升级

Windows + 中文用户名的坑（本机实测） encore daemon 通过 unix socket 与 CLI 通信，socket 文件默认落在 %LOCALAPPDATA% 下；用户名含中文时 bind 失败、daemon 起不来，所有 encore 命令挂死。 变通：把 LOCALAPPDATA 环境变量重定向到纯 ASCII 路径（如 D:\encore-data）再运行 encore。建议封装进项目的 dev.ps1 启动脚本（本机 B2B 项目即如此），团队成员无感知。

三、创建第一个应用

encore app create

交互式流程会问四件事：

1. 应用名（成为 app id 的一部分）；
2. 语言：选 TypeScript；
3. 模板：Hello World（带示例服务）或 Empty app（从零开始，实战章都用它）；
4. AI 工具适配：是否生成 CLAUDE.md / .cursorrules 等 AI 规则文件（第 18 章详解，此处可先跳过）。

不登录 Encore 账号也能创建和本地开发；登录（encore auth signup / login）后才能使用 Encore Cloud 部署与 secret 云端存储。

生成的项目结构（Hello World 模板）

your-app/
├── encore.app          # 应用清单：app id、全局配置（如 CORS）
├── package.json        # 唯一的根级 package.json（monorepo 约定）
├── tsconfig.json
└── hello/              # 一个服务 = 一个目录
    ├── encore.service.ts   # 服务声明（必须）
    └── hello.ts            # API 端点

encore.app 是应用清单文件，JSON 格式：

{
  "id": "your-app-abc2",
  "lang": "typescript"
}

后续的 CORS 配置（第 12 章）也写在这里。

包管理约定 Encore.ts 应用默认单一根级 package.json（前端依赖也放这里）。如果拆多包，Encore 应用本身必须仍是一个包；其他包需预编译成 JavaScript。

四、encore run：不只是启动服务

cd your-app
encore run

这条命令依次做了：

1. 静态分析源码，构建应用模型；
2. 发现数据库/消息声明 → 自动拉起 Docker 容器（Postgres 用 encoredotdev/postgres 镜像，内置 pgvector 与 PostGIS 扩展）；
3. 自动执行数据库迁移；
4. 注册所有 service / API / cron / topic / subscription；
5. 启动 API 服务于 http://localhost:4000；
6. 打开本地开发仪表盘 (Local Dev Dashboard) 于 http://localhost:9400。

修改代码 → 热重载 + 应用模型重建，无需重启。常用参数：encore run --debug、--watch=true。

五、本地开发仪表盘五大功能

http://localhost:9400 上的仪表盘是 Encore 开发体验的核心，五个面板：

体验一下追踪：在 API Explorer 里调一次接口，切到 Tracing 面板，能看到这次请求经过的每一层——包括 SQL 语句原文和参数。这一切没写过一行埋点。

六、daemon 机制与排障

CLI 背后有一个常驻 daemon 进程负责编译、运行、代理。行为异常时的排障顺序：

encore daemon         # 重启 daemon（解决大多数"卡住"问题）
encore daemon env     # 输出环境诊断信息

常见问题速查：

七、写一个最小应用（不用模板）

理解约定的最好方式是从 Empty app 手写。完整流程：

encore app create   # 选 Empty app
cd my-app
mkdir hello

// hello/encore.service.ts —— 声明"这个目录是一个服务"
import { Service } from "encore.dev/service";
export default new Service("hello");

// hello/hello.ts —— 定义一个 API
import { api } from "encore.dev/api";

export const greet = api(
  { expose: true, method: "GET", path: "/hello/:name" },
  async ({ name }: { name: string }): Promise<{ message: string }> => ({
    message: `Hello ${name}!`,
  }),
);

encore run
curl http://localhost:4000/hello/world
# → {"message": "Hello world!"}

两个文件换来的东西：HTTP 路由 + 路径参数解析 + 类型校验 + 自动文档 + 追踪。打开 localhost:9400 确认 Service Catalog 里已经出现 hello.greet 的文档页。

三条起步约定（第 3 章展开）

• 服务 = 目录 + encore.service.ts，服务不能嵌套；
• API 默认私有（expose: false），公网访问必须显式 expose: true；
• 路径支持 :param 占位与 *wildcard 通配。

八、常见误区

1. 不装 Docker 就跑带数据库的应用——encore run 会卡在基础设施开通。
2. 在子目录各建 package.json——Encore 应用要求单一根级包。
3. 把 encore.app 当可有可无的配置——它是应用身份（app id）与全局配置（CORS）的家。
4. Windows 中文用户名环境不做 LOCALAPPDATA 重定向，把 daemon 挂死当框架 bug。
5. 出问题先重装——先 encore daemon 重启，绝大多数"玄学问题"是 daemon 状态。

九、实践练习

1. 安装 CLI，用 Hello World 模板建一个应用，跑通 curl。
2. 打开 localhost:9400，在 API Explorer 里调 3 次接口，到 Tracing 面板找出最慢的一次，看它的耗时分布。
3. 从 Empty app 手写第七节的最小应用，故意把 encore.service.ts 删掉再 encore run，观察编译错误信息——体会"偏离约定即编译错误"。
4. 把 path: "/hello/:name" 改成 /hello/:name/:lang，让响应根据 lang 返回中英文问候，观察热重载。

十、总结

1. 安装三平台一条命令；本地开发的隐性前置是 Docker；Windows 中文用户名需重定向 LOCALAPPDATA。
2. encore app create 的模板与 AI 工具适配是两个关键选项；项目结构核心是 encore.app + 单一根级 package.json + 每服务一目录。
3. encore run = 静态分析 + 自动基础设施 + 自动迁移 + 热重载 + 仪表盘。
4. 本地仪表盘五大面板替代了 Swagger、Postman、Jaeger 和手画架构图。
5. daemon 是 CLI 的后台引擎，异常先 encore daemon 重启。

请继续阅读：第3章:服务与 API。

原始资料引用

• Installation
• Hello World
• Local Dev Dashboard
• CLI Reference

Related Documents

• 第1章:开篇
• 第3章:服务与 API