📦 Docker Webapp

一个简化前端 Web 项目部署的 Docker 运行环境，通过环境变量动态替换配置，实现一次构建，处处部署。

✨ 功能特性

• 🚀 环境变量注入 - 启动时自动替换前端代码中的环境变量占位符
• 🔧 零配置部署 - 无需重新构建即可适配不同环境
• 🐳 Docker 原生支持 - 基于 Nginx Alpine 镜像，轻量高效
• 📁 多格式支持 - 自动处理 .html.js.css.json 文件
• 🛡️ 智能路径处理 - 自动处理斜杠，避免路径拼接问题
• ⚡ 高性能 - 内置 Gzip 压缩和静态资源缓存策略

🎯 解决什么问题

前端项目打包后，后端 API 地址、环境变量等配置已硬编码到构建产物中。当需要在不同环境（开发、测试、生产）部署时，通常需要重新构建项目。

本项目通过环境变量动态替换机制，实现：

1. 构建时将配置项以变量名形式打包（如 API_SERVER_URL）
2. 部署时通过环境变量传入实际值
3. 容器启动时自动替换，无需重新构建

📥 快速开始

拉取镜像

docker pull ghcr.io/nekoimi/webapp:latest

运行示例

git clone https://github.com/nekoimi/webapp.git
cd webapp
docker-compose up -d

访问 http://localhost 查看效果

🛠️ 使用方法

1. 准备前端项目

在前端代码中使用环境变量名称作为占位符：

<!-- index.html --><script>constapiUrl='API_SERVER_URL';// 将被替换为实际值constappName='APP_NAME';// 将被替换为实际值</script>

2. 使用 Docker Compose

version: "3.6"services:
webapp:
image: ghcr.io/nekoimi/webapp:latestports:
- "80:80"environment:
# 以 WEBAPP_ENV. 为前缀设置环境变量WEBAPP_ENV.API_SERVER_URL: https://api.example.comWEBAPP_ENV.APP_NAME: 我的应用WEBAPP_ENV.BASE_URL: /app/WEBAPP_ENV.USERNAME: adminWEBAPP_ENV.PASSWORD: secret123volumes:
- ./dist:/workspace # 挂载前端构建产物

3. 构建自定义镜像

FROM ghcr.io/nekoimi/webapp:latest
COPY ./dist /workspace

docker build -t my-webapp .
docker run -p 80:80 -e WEBAPP_ENV.API_URL=https://api.example.com my-webapp

⚙️ 配置说明

环境变量

变量名	说明	示例
WEBAPP_ENV.<KEY>	自定义配置项，将被替换到前端代码中	WEBAPP_ENV.API_URL=https://api.com
PORT	HTTP 服务端口（默认 80）	PORT=8080
TZ	时区设置（默认 Asia/Shanghai）	TZ=Asia/Shanghai

支持的文件类型

以下文件类型会自动进行环境变量替换：

• .html - HTML 文件
• .js - JavaScript 文件
• .css - 样式文件
• .json - JSON 配置文件

路径处理规则

工具会自动处理斜杠，避免以下问题：

• //api → /api（自动去重）
• api/ + /endpoint → api/endpoint（智能拼接）

📁 项目结构

.
├── main.go # Go 部署工具源码
├── Dockerfile # 镜像构建配置
├── docker-compose.yaml # 示例编排文件
├── conf/ # Nginx 配置
│ ├── nginx.conf # Nginx 主配置
│ └── default.conf.tpl # 站点配置模板
├── example/ # 示例前端项目
│ ├── index.html
│ ├── css/
│ └── js/
└── 99-run-webapp.sh # 容器启动脚本

🔧 工作原理

1. 启动阶段：容器执行 99-run-webapp.sh 脚本
2. 环境加载：webapp 程序读取 WEBAPP_ENV.* 前缀的环境变量
3. 文件复制：将 /workspace 目录内容复制到 Nginx 根目录
4. 变量替换：扫描 .html.js.css.json 文件，替换占位符
5. 权限设置：设置文件权限，启动 Nginx 服务

🌟 最佳实践

前端项目配置

建议使用统一的环境变量命名规范：

// config.jsconstconfig={apiUrl: 'API_SERVER_URL',appName: 'APP_NAME',baseUrl: 'BASE_URL',version: 'APP_VERSION'};

CI/CD 集成

# .github/workflows/deploy.yml
- name: Deploy to Productionrun: | docker run -d \ -p 80:80 \ -e WEBAPP_ENV.API_SERVER_URL=${{ secrets.PROD_API_URL }} \ -e WEBAPP_ENV.APP_NAME=生产环境 \ -v $(pwd)/dist:/workspace \ ghcr.io/nekoimi/webapp:latest

🐛 故障排查

环境变量未生效

1. 检查变量名是否以 WEBAPP_ENV. 开头
2. 查看容器日志：docker logs <container_id>
3. 确认挂载目录正确：/workspace 应包含前端文件

权限问题

# 检查文件权限
docker exec<container_id> ls -la /usr/share/nginx/html
# 修复权限
chmod -R 755 ./dist

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

---

Made with ❤️ by nekoimi