ZJUI-Learn Windows本地运行指引（Docker Desktop，无WSL）

本文档适用于：

• Windows 10/11
• Docker 桌面
• 项目代码位于Windows本地磁盘（如C:\...）
• 不使用 WSL 内部开发环境

---

1. 前置准备

1. 启动Docker Desktop（状态为Running）。
2. 打开PowerShell，进入仓库上级目录：

cd "C:\Users\xwy12\Desktop\my-project\zjuilearn"

1. 确认项目目录存在：

ls

应参见 ZJUI-Learn 目录。

---

2. 一键启动命令（可直接复制）

这是推荐的“本地Windows + Docker”启动方式。

docker run -it --rm -p 3000:3000 -w /PrairieLearn -v "${PWD}:/PrairieLearn" prairielearn/prairielearn /bin/bash

进入容器后执行：

cd ZJUI-Learn
make dev

浏览器访问：

• http://localhost:3000

---

3. 日常开发推荐流程

首次进入容器：

cd ZJUI-Learn
make deps
make dev

后续开发（更快）：

cd ZJUI-Learn
pnpm dev

热重启：

• 在 nodemon 前台输入 rs

---

4. 常用命令

在容器内项目根目录 ZJUI-Learn 执行：

# 运行单个测试（示例）
pnpm test apps/prairielearn/src/tests/homepage.test.ts

# 查看类型/构建（按需）
make build

---

5. 常见问题与处理

5.1 port 3000 is already allocated

说明 3000 端口被占用，改端口映射即可：

docker run -it --rm -p 3001:3000 -w /PrairieLearn -v "${PWD}:/PrairieLearn" prairielearn/prairielearn /bin/bash

然后访问 http://localhost:3001。

5.2 make: *** No rule to make target 'dev'

通常是容器内路径不对。请先：

cd ZJUI-Learn
make dev

5.3 启动很慢（1~2 分钟）

这是Windows磁盘挂载开发的常见现象，特别是第一个字节码/依赖准备阶段。可通过以下方式减少：

• 首发 make deps 后续，后续多用 pnpm dev
• 不频繁重启容器，优先 rs 重启服务
• 给 Docker Desktop 分配更多的 CPU/内存

5.4 页面上传 AI 报 fetch failed / TLS 握手超时

若容器内访问 https://example.com 都超时，容器 HTTPS 出网问题，不是代码问题。建议：

1. 重启Docker桌面；
2. 执行wsl --shutdown（即使你没有WSL内开发，同样影响Docker网络栈）；
3. 再次启动容器验证。

---

6. 退出与清理

• 停止服务：Ctrl + C
• 退出容器：exit
• 因为使用了--rm，集装箱会自动删除。