diff --git a/.gitignore b/.gitignore
index 5684b04..ec693dd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,6 @@ docs/
 # 前端
 node_modules/
 web/dist/
+
+# 本地开发数据
+.dev-data/
diff --git a/README.md b/README.md
index e3f5b57..7ccf7f7 100644
--- a/README.md
+++ b/README.md
@@ -28,9 +28,21 @@ docker run -d --name rawmark \
 
 ## 开发
 
+需要 Go 1.27+ 与 Node 24+。开发时不必构建前端或 Docker 镜像，开两个终端：
+
 ```sh
-cd web && npm install
-npm run dev        # 前端开发服务器，/api 转发到 127.0.0.1:8080
-npm run typecheck && npm test
-go test ./internal/...
+# 终端 1：后端（-tags dev 不嵌入前端资源，数据放在仓库下的 .dev-data/）
+RAWMARK_DATA=.dev-data RAWMARK_ADDR=127.0.0.1:8080 go run -tags dev ./cmd/rawmark
+
+# 终端 2：前端（热更新，/api 与 WebSocket 转发到 127.0.0.1:8080）
+cd web && npm install && npm run dev
+```
+
+浏览器打开 http://localhost:5173 ，启动码在 `.dev-data/setup-code.txt`。手机调试用 `npm run dev -- --host`，再访问 `http://<电脑 IP>:5173`。
+
+检查：
+
+```sh
+cd web && npm run typecheck && npm test
+go vet -tags dev ./... && go test ./internal/...
 ```
diff --git a/web/embed.go b/web/embed.go
index 40a53c6..ca11a34 100644
--- a/web/embed.go
+++ b/web/embed.go
@@ -1,4 +1,7 @@
+//go:build !dev
+
 // Package web 把前端构建产物（web/dist，由 npm run build 生成）嵌入 Go 二进制。
+// 开发时使用 -tags dev，前端由 Vite 开发服务器提供，见 embed_dev.go。
 package web
 
 import (
diff --git a/web/embed_dev.go b/web/embed_dev.go
new file mode 100644
index 0000000..8908ee4
--- /dev/null
+++ b/web/embed_dev.go
@@ -0,0 +1,14 @@
+//go:build dev
+
+package web
+
+import (
+	"io/fs"
+	"os"
+)
+
+// Dist 在开发模式下直接读取磁盘上的 web/dist（未构建时为空，页面由 Vite 开发服务器提供），
+// 因此无需先构建前端即可 go run
+func Dist() fs.FS {
+	return os.DirFS("web/dist")
+}