前言

当前开发环境不够统一，在一些细节上有些不同，虽然在90%的工作中不影响；但偶尔总会出现一些因为环境、版本等导致的问题。如：

Windows下大小写不敏感；
Windows下文件行尾问题：CRLF/LF
nodejs运行版本不同

……

诸如以上的问题还有很多，不常出现，但一旦出现，就是一个很坑的点。结合我们目前部署环境使用docker的经验，制定一套以docker为运行环境的本地开发流程是我能i想到的一个解决方案。

目标

环境配置简单，易上手
热更新
debug模式
项目启动快捷
无需了解项目结构即可本地运行（对应头豹项目和脑力勤，不了解项目结构的情况下很运行，即使有文档，也需要很大成本理解）

开发环境搭建

vscode+docker+git

基础环境（可以跳过）

wsl2安装（win环境）

适用于 Linux 的 Windows 子系统文档

安装

官方的教程已经足够详细，安装教程中的步骤执行即可。以下简单说下旧版安装步骤，新版只要一个wsl install即可。

开启相关的windows服务：（需要重启）
1. 可视化操作：控制面板=>程序=>启用或关闭windows服务
2. 命令行开启：管理员运行powershell

# 启动适用于windows的linux子系统
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启动虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

2. 安装Linux发行版：打开 Microsoft Store，并选择你偏好的 Linux 分发版。（验证的版本为：Ubuntu 20.04.6 LTS） 3. 安装完成后需要设置用户名密码，自行设置即可。

通过wsl2使用vscode

learn.microsoft.com/zh-cn/windo…

常见问题

Wsl提示未注册

解决方案：

设置>已安装的应用>适用于windows的linux子系统>卸载
管理员powershell：wsl --install
wsl安装系统对应的最新版本（不安装的话会导致docker无法启动：unexpected wsl error）

WslRegisterDistribution failed with error: 0x8007019e（虚拟机平台未开启）
1. 先检查下wsl命令是否正常，如果wsl提示未注册，打开ubuntu时也会出现当前错误

解决方案：

管理员运行pawershell：输入命令Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
控制面板：启用或关闭windows功能>虚拟机平台>启用

docker安装

www.docker.com/products/do…

官网下载docker-desktop，按照提示进行安装即可。（windows环境下需先启用wsl2）

windows下安装事项

设置wsl2环境 a. 默认使用的是wsl2，无需处理 b. 需要选择发行版：如安装Ubuntu，则打开Ubuntu的选项

安装git

git-scm.com/download/li…

mac/Linux环境下直接下载安装即可。windows下需要注意，要安装在wsl2下（找对应wsl的Linux安装方式）。

安装vscode

code.visualstudio.com/download

官网下载直接安装即可。

备注：windows安装参考：learn.microsoft.com/zh-cn/windo…

项目设置

以我们日常的前后端分离项目为案例介绍思路，并附核心代码。

基础运行

项目结构（windows需要在wsl中拉取项目）

-- .vscode  // 配置debug
    -- launch.json
-- backend
    -- src
    -- docker_run.sh // 用于启动容器，有docker-compose.yml的情况下可以不用关注
    -- entrypoint.sh
    -- Dockerfile
-- frontend
    -- src
    -- docker_run.sh
    -- entrypoint.sh
    -- Dockerfile
-- docker-compose.yml

2. Backend

Dockerfile

FROM node:18.18-alpine
RUN echo "http://mirrors.aliyun.com/alpine/v3.18/main/" > /etc/apk/repositories && \
  echo "http://mirrors.aliyun.com/alpine/v3.18/community/" >> /etc/apk/repositories
RUN apk add tzdata curl
RUN cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

USER root

ENV PORT=3000
ENV APP=local_docker_backend
ENV ROOT=/var/www
ENV LOG_DIR=/var/log
ENV NODE_ENV=dev

ENV FRONTEND_DIR=/var/frontend/dist

RUN npm install -g @nestjs/cli  --registry=https://registry.npmmirror.com

COPY ./entrypoint.sh /
RUN chmod +x /entrypoint.sh

# COPY ./prod.env /var/www/prod.env

WORKDIR /var/www

HEALTHCHECK --interval=30s --timeout=2s --start-period=10s --retries=2 CMD curl --fail localhost:${PORT}/health || exit 1
ENTRYPOINT [ "sh", "/entrypoint.sh" ]

entrypoint.sh
- 为了可以热更新，需要以数据卷挂载的方式将代码映射到目录中，所以需要指定一个sh文件作为启动脚本

cd /var/www
echo '安装后端端依赖'
npm install --registry=https://registry.npmmirror.com

npm run start:debug // nestjs需要以debug方式启动，并指定debug端口

echo 'Starting...'

3. Frontend

Dockerfile

FROM node:18.18-alpine
RUN echo "http://mirrors.aliyun.com/alpine/v3.18/main/" > /etc/apk/repositories && \
  echo "http://mirrors.aliyun.com/alpine/v3.18/community/" >> /etc/apk/repositories
RUN apk add tzdata curl
RUN cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

COPY ./entrypoint.sh /
RUN chmod +x /entrypoint.sh

# COPY ./prod.env /var/www/prod.env

WORKDIR /var/www

# HEALTHCHECK --interval=30s --timeout=2s --start-period=10s --retries=2 CMD curl --fail localhost:${PORT}/health || exit 1

ENTRYPOINT [ "sh", "/entrypoint.sh" ]

entrypoint.sh

echo 'Building frontend...'
cd /var/frontend
echo '安装前端依赖'
npm install --registry=https://registry.npmmirror.com

npm run dev

echo 'Starting...'

4. docker-compose.yml

services:
  local_docker_backend:
    build: ./backend
    ports:
      - 3000:3000
      - 9229:9229 // nodejs默认debug端口
    environment:
      - NODE_ENV: dev
    volumes:
      - ./backend:/var/www
      - ./backend/dev.env:/var/www/dev.env
  local_docker_frontend:
    build: ./frontend
    ports:
      - 8080:8080
    volumes:
      - ./frontend:/var/frontend

networks:
  local_docker_network:
    name: local_docker_network
    driver: bridge

5. 运行项目

// 进入项目根目录
docker-compose up -d

vscode使用debug模式

配置vscode配置文件

launch.json

{
  // 使用 IntelliSense 了解相关属性。
  // 悬停以查看现有属性的描述。
  // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach", // 调试的方式：附加到已经运行的程序上
      "name": "Docker: Attach to Node",
      "port": 9229, // 调试的端口号
      "address": "localhost", // 地址
      "sourceMaps": true, // ts编辑映射
      "restart": true,
      "localRoot": "${workspaceFolder}/backend", // 本地代码的根路径
      "remoteRoot": "/var/www", // 远端docker容器中代码对应路径
      "resolveSourceMapLocations": ["${workspaceFolder}/backend/**", "!**/node_modules/**"],
      "internalConsoleOptions": "openOnSessionStart"
    }
  ]
}

统一项目开发环境：vscode+docker

前言

目标