跳转到内容
选择主题
选择语言简体中文

后端

应用可以带一个后端: 一个导出 fetch 的模块, 或任何调 listen() 的 Node.js / Bun 服务器 (Express、Hono、Fastify ……). 页面用普通的 fetch('/api/…') 访问它.

应用后端在 macOS、Linux 和 Windows 上都能跑. Windows 上运行时用另一种方式连到后端; 见 Windows 上.

acdev new my-app --backend 生成的 server.ts:

export default {
fetch(request: Request): Response {
const url = new URL(request.url)
if (url.pathname === '/api/hello') return Response.json({ hello: 'world', at: new Date().toISOString() })
return new Response('not found', { status: 404 })
},
}

页面里:

const answer = await (await fetch('/api/hello')).json()

export default { fetch } 在 Bun 和 Node.js 上都能用: Node.js 上 acdev 的 preload 用 node:http 把它跑起来, 请求和回应都是 WHATWG 的 Request / Response, 支持流式 body. (Node.js 上没有 WebSocket 升级.)

也可以自己 listen:

import { createServer } from 'node:http'
createServer((req, res) => res.end('hi')).listen(3000)

要让后端自己渲染页面 (用 Hono、JSX、模板 ……在服务端生成 HTML, 不用 acdev 认得的框架), 把入口设成 /:

{ "type": "app", "id": "my-app", "label": "My app", "icon": "app", "entry": "/" }

这时窗口从后端打开 /, 它跳到的每个页面 (链接、location.href、表单) 也都来自后端; public/ 仍然在应用的根路径下提供. 没有后端时, acdev check 和 acdev build 报错停下; 以 / 结尾的入口只接受 / 这一个. 在服务端渲染的框架 (Next.js、Nuxt、SvelteKit ……) 自动这样设置; 见 前端框架.

不写 backend 时, acdev 按顺序找第一个存在的:

server.ts server.js src/server.ts src/server.js server/index.ts server/index.js backend/index.ts backend/index.js

显式指定, 或关掉:

{ "backend": { "entry": "api/main.ts", "port": 8080 } }
{ "backend": false }

port 默认 3000, 是后端以为自己在听的端口.

应用的后端不在宿主机上开 TCP 端口. 构建时 acdev 在后端旁放一个 preload (acde-listen.js), 它把 Bun.serve、Bun.listen 和 net / http / https / tls / http2 的 listen(P) 都换成一个 unix socket <应用的 socket 目录>/P.sock. 没给端口时取 PORT / BUN_PORT / NODE_PORT, 否则用 3000.

所以:

  • 两个应用都 listen(3000) 不会冲突.
  • 页面访问同源的路径 (/api/x), 或 http://localhost:<端口>/… (以及 127.0.0.1、[::1]、0.0.0.0), 都会送到自己的后端.
  • 指定端口的 UDP bind 会被拒绝 (EACCES); 原生扩展自己开的端口不受此限制.

同一份构建产物在 Windows 上也能跑, 那里后端同样不开 TCP 端口, 也不开命名管道. 运行时怎么连到它, 看是什么在跑它:

  • Bun: 和 macOS、Linux 上一样, listen(P) 变成一个 socket 文件 P.sock. 它所在的目录 (ACDE_APP_SOCKETS) 每次启动后端时重新建, 只有当前用户和系统能打开.
  • Node.js: Node.js 在 Windows 上不能听 socket 文件, 所以根本没有东西在听. preload 留住调了 listen(P) 的那个服务器, 运行时通过一条通到后端进程的私有管道, 把每个连接 (HTTP 请求和 WebSocket 升级) 交给它. 后端拿到 ACDE_APP_CHANNEL=fd, 没有 ACDE_APP_SOCKETS. 在这之前的 acdev 构建的后端在 Windows 上不会被启动; 日志里写 not started: acde-listen.js does not support the Windows channel (built by an older acde: acdev build it again).

在 Windows 上停后端时, 运行时请它自己关闭: 它不再接新连接, 做完进行中的请求, 然后退出; 3 秒后运行时结束它, 连同它启动的进程.

acdev build 把后端打成单个 ES 模块 backend/server.js (target node): npm 包打进去, Node 内置模块和 bun / bun:* 保留为导入. Bun 和 Node.js 都能跑同一份产物.

  • 应用的第一个窗口打开时启动后端, 最后一个窗口关掉时停掉 (macOS 和 Linux 上先 SIGTERM, 3 秒后 SIGKILL; Windows 见 上文). 一分钟里崩溃第 4 次后不再自动重启.
  • PATH 上有 bun 时用 Bun 跑, 否则用 Node.js (≥ 22.3). acdev dev 按工程的 JS 运行时选.
  • 环境变量是新建的: ACDE_APP_ID、ACDE_APP_DATA、ACDE_APP_SOCKETS、PORT、NODE_ENV=production, 再加会话的 HOME、PATH、LANG 等, 以及下面说的代理变量. 除此之外不会继承你终端里的环境.
  • 代理设置会传给后端. 会话里设了 http_proxy、https_proxy、all_proxy 中的任何一个时, 后端拿到会话里的 http_proxy、https_proxy、all_proxy 和 no_proxy, 原样不变 (macOS 和 Linux 上小写和大写两种名字都按设的传; Windows 上变量名不分大小写, 用大写的名字). 一个都没设时, 后端拿到系统的手动代理, 和页面用的是同一份设置. 只有 Windows 和 macOS 有这种设置: Windows 上是用户 Internet 设置里的 HTTP 代理 (socks= 项变成 all_proxy=socks4a://host:port), 用大写的名字设; macOS 上是网络设置里的 HTTP、HTTPS 和 SOCKS 代理 (SOCKS 变成 socks5h://host:port), 小写和大写两种名字都设. 这时 no_proxy 里是会话的 no_proxy、换成 no_proxy 写法的系统例外 (*.example.com 变成 .example.com, 192.168.* 变成 192.168.0.0/16; 其它通配符、Windows 的 <local> 和 macOS 的「排除简单主机名」没有 no_proxy 的写法, 不带上), 以及 localhost,127.0.0.1,::1. 代理自动配置脚本和自动发现代理是按 URL 回答的, 没法写成变量, 所以用它们时后端拿不到系统代理 (Windows 上只勾了「自动检测设置」时, 手动代理照样传). 每次启动后端时读一遍这些设置. Linux 没有可读的系统代理设置: 那里只算会话的变量. 你用的 HTTP 客户端还得自己认这些变量 (Bun 的 fetch 和很多 npm 客户端认; Node.js 内置的 fetch 默认不认).
  • 工作目录是 $XDG_DATA_HOME/acde/apps/<id>/, 可以在这里放应用自己的数据.
  • 在 macOS 和 Linux 上, socket 放在会话的运行时的一个目录里 (ACDE_APP_SOCKETS). 每个会话有自己的目录, 在 acdev 的运行时目录下的 <运行时的 pid>/<id>, 后端停了就删掉: macOS 上是 $TMPDIR/acde-<uid>, 别处是 XDG_RUNTIME_DIR 里的 acde/ (Linux 上没设时是 /run/user/<uid>). socket 路径比系统允许的长 (macOS 104 字节, Linux 108) 时后端不启动, 日志里会说.
  • 后端的输出进运行时的日志, 前缀 [<id>#backend]. acdev dev 会把它打在终端里.

不经运行时单独调试构建好的后端时, 给它一个 socket 目录, 并载入 acdev build 放在它旁边的 preload (下面的命令是 macOS 和 Linux 上的):

终端窗口
acdev build
cd .acde/backend
ACDE_APP_SOCKETS=/tmp/my-app-sockets bun --preload ./acde-listen.js server.js
curl --unix-socket /tmp/my-app-sockets/3000.sock http://localhost/api/hello