uni-app Docker部署失败主因是构建产物托管配置错误，非框架本身问题；常见现象为容器启动后退出、API 404 或静态资源加载失败，根源在于Nginx前台运行缺失、volume挂载路径错误、nginx.conf未适配history路由、npm install镜像源或依赖配置不当，以及跨域/反向代理未正确设置。
uni-app 本身是前端框架，不直接运行在 Docker 容器里；所谓“Docker 容器化部署失败”，实际是指 uni-app 构建产物（如 H5 静态资源）被 Nginx 或 Node.js 服务容器托管时启动/访问失败。问题根源几乎全在容器配置或构建流程上，而非 uni-app 代码本身。
docker-compose up -d 启动后容器立即退出
这是最常见现象，尤其当你用 nginx 容器 serve uni-app 的 dist/h5 目录时。
- 根本原因：Nginx 启动后找不到默认首页（
index.html），或 HTML 路径写死为/导致 JS/CSS 404，Nginx 进程因健康检查失败或无前台进程自动退出 - 确认方式：
docker logs看是否报open() "/usr/share/nginx/html/index.html" failed (2: No such file or directory) - 关键修复点：
- 确保
docker-compose.yml中volumes挂载路径正确，例如./dist/h5:/usr/share/nginx/html:ro，且本地dist/h5目录已存在（先手动运行npm run build:h5） - 在
nginx.conf里显式指定root /usr/share/nginx/html;和try_files $uri $uri/ /index.html;（支持 Vue Router history 模式） - 禁止使用
command: nginx -g "daemon off;"以外的后台启动方式——Nginx 必须以前台模式运行，否则容器会认为主进程结束而退出
- 确保
构建镜像时 npm install 失败或 node_modules 缺失
你在 Dockerfile 里执行 npm install，但构建卡住、报错或生成的镜像里没有依赖，导致 H5 页面白屏或控制台报 Cannot find module。
- 典型错误：
error code EACCES（权限）、network timeout（拉包超时）、node-sass not found（二进制缺失） - 必须处理的三件事：
- 换国内镜像源：在
Dockerfile的npm install前加RUN npm config set registry https://registry.npmmirror.com - 跳过可选依赖：加
--no-optional参数，避免node-sass等编译型包失败 - 不要盲目
COPY node_modules：应先COPY package*.json，再RUN npm install，最后COPY . .，利用 Docker 层缓存加速且避免本地node_modules权限污染容器
- 换国内镜像源：在
容器内页面能打开，但 API 请求 404 或跨域
uni-app H5 版本跑在容器里，访问自己后端接口返回 404 或 CORS 错误，不是后端没启，而是请求发到了容器外的地址。
- uni-app 的
uni.request默认走浏览器当前域名，即你访问http://localhost:8080，它就往http://localhost:8080/api/xxx发请求 —— 但你的后端服务很可能在另一个容器（比如api服务），不在同一 host - 解决方案只有两个，选其一：
- 前端改 baseURL 为后端容器名（如
http://api:3000），并确保 Nginx 容器和 API 容器在同一个自定义网络（docker-compose.yml里声明networks并让两者加入） - 更推荐：用 Nginx 反向代理，在
nginx.conf里加location /api/ { proxy_pass http://api:3000/; }，前端仍请求/api/xxx，由 Nginx 转发到后端容器 —— 这样无需改代码，也规避了浏览器跨域限制
- 前端改 baseURL 为后端容器名（如
最容易被忽略的是：uni-app 的 manifest.json 里 H5 节点下的 router 模式（hash 或 history）必须和 Nginx 配置对齐；用 history 却没配 try_files，所有子路由都会 404，而且这个错误不会出现在容器日志里，只能靠浏览器 Network 面板看返回状态码。
