# franka_description Docker构建因UID/GID与基础镜像用户冲突失败

> 原文链接：https://robotics.hellobike.com/pitfalls/2026-08-05-franka-description-28
> 频道：pitfalls | 更新日期：2026-08-05 | 标签：auto, github-issue, franka_description
> 核心摘要：Dockerfile中groupadd/useradd命令因ID冲突报错，需在创建用户前检测并删除同ID旧用户或改用条件创建逻辑。

# franka_description Docker构建因UID/GID与基础镜像用户冲突失败

::: v-pre
> 本文由 AI 根据公开内容整理，可能有误，请以原文为准：[Dockerfile fails to build when UID/GID matches with the existing docker image user](https://github.com/frankarobotics/franka_description/issues/28)（GitHub frankarobotics/franka_description #28）

**状态**：已解决

## 问题

在osrf/ros:jazzy-desktop基础镜像上构建franka_description时，若宿主机传入的USER_UID/USER_GID（如1000:100）与镜像内已有ubuntu用户ID重合，RUN groupadd和useradd命令会报GID/UID already exists错误导致构建中断。

## 环境

基础镜像osrf/ros:jazzy-desktop；franka_description仓库main分支；宿主机用户UID:GID为1000:100、1000:1000等常见组合；Ubuntu系统默认首用户账户。

## 解决办法

1. 在Dockerfile中groupadd/useradd指令前添加`RUN if id -u $USER_UID ; then userdel $(id -un $USER_UID) ; fi`以清理冲突ID。
2. 或采用非破坏性修复：仅在ID未被占用时创建用户组与用户，后续操作统一使用UID:GID引用账户而非用户名。
3. 确保useradd命令包含`-s /bin/bash`参数以正确设置登录Shell。
4. 验证修复后HOME目录、/workspaces所有权、XDG_RUNTIME_DIR及xacro工具均正常可用。

讨论原作者：@arntanguy 等，版权归原作者所有。
:::

## 原始参考来源 (Sources)

- [GitHub frankarobotics/franka_description #28：Dockerfile fails to build when UID/GID matches with the existing docker image user](https://github.com/frankarobotics/franka_description/issues/28)