简介：一份面向 JIRA 管理员、项目经理和插件开发者的批量建单工具，基于 Java 实现，支持普通用户通过 CSV 一次性创建多个 JIRA 问题。不同于传统导入器，该插件会在创建过程中识别并强制执行必填字段、权限及其他配置约束，确保批量生成的问题完整且符合项目规则，适用于初始化建单、缺陷迁移或按计划批量创建任务等场景。资源压缩包共 93 个文件，约 12MB，主体是 32 个 Java 源码文件，另有 14 个 CSV 模板与样例、11 个 VM 页面模板、6 个 JS 脚本和 6 个 XML 配置；CSV 提供批量数据输入样例，VM 与 JS 负责界面交互，XML 描述模块与依赖，同时包含 PNG/PSD 图标素材和 marketing 物料，配合 src/test 测试目录，结构完整，便于按模块研读。目前已有 725 人学习或下载。通过阅读源码，可掌握 JIRA 插件中 CSV 解析、权限受限下的 issue 创建、配置校验复用等关键实现；界面模板和图标资源也能帮助快速搭建或二次美化插件入口，适合用于学习、二次开发或直接部署。
1. 普通用户批量建 JIRA 工单：一份 CSV 就把重复录入从半小时压到一分钟
做过 JIRA 运维的人都知道，批量创建问题在默认界面里从来不是给普通用户准备的。项目管理员可以进“批量操作”，登录用户却只能一条条点“创建”，遇到上几十条数据迁移、版本复盘、硬件盘点这类场景，一下午就耗在重复点击上了。这个名为 bulk-create-issues-for-jira 的插件，切入点很直接：把入口开放给普通登录用户，让他们直接上传 CSV 文件，一次创建多个 JIRA 问题，而不需要被授予项目管理员权限。它用 Java 实现，挂在 JIRA 服务端，天然适配现有的用户权限体系——你不需要在系统层面给任何人开管理员，只要单独分配一个业务权限即可。适合谁？日常要录批量工单的测试、运营、客服、硬件管理团队，以及不想把项目管理员权限散出去的 JIRA 管理员。
2. 从安装到首单落地：这条批量创建链路每一步都在干什么
2.1 安装与全局权限分配：普通用户怎么拿到入口
插件本质是一个 JIRA Server/Data Center 的 jar 包，通过管理后台的“管理应用”上传即可。上传完成后，并不会自动给所有人生成菜单，先要在“应用权限”里把这个插件的“批量创建”权限勾选给需要使用的用户组。常见做法是新建一个名为“工单批量录入”的用户组，把测试、客服、运营人员拉进去，而不是直接给项目角色——注意这个插件用的是全局权限，跟项目角色是两套体系。
# 以管理员身份调用 REST API 确认插件已激活（本地 JIRA 实例示例） curl -u admin:yourpassword \ -H "Accept: application/json" \ "http://localhost:8080/rest/plugins/1.0/?os_authType=basic" | grep -i "bulk-create" # 期望输出里能看到类似 "key": "bulk-create-issues-for-jira", "enabled": true 的片段这段命令作用是查询 JIRA 插件管理接口，确认插件包已经被正确加载。参数说明：/rest/plugins/1.0/是插件管理标准端点，os_authType=basic表示走基础认证，返回的 JSON 里 grep 出插件关键词即可判断状态。实际生产环境我一般会直接看后台“管理应用”列表，比 curl 直观，但脚本化排查时这个接口更好用。
权限分配完成后，普通用户刷新 JIRA 页面，顶部菜单栏就能看到“批量创建”入口。这里有个容易漏的点：插件激活后如果用户看不到入口，先查用户是否在权限勾选的组里，而不是急着重装插件。浏览器缓存和 JIRA 的系统缓存都可能影响菜单显示，强制刷新一次通常就出来了。
2.2 模板下载与首张 CSV 的准备清单
进入“批量创建”页面后，第一步是下载 CSV 模板。这个模板文件本身不复杂，但它是后续所有配置的锚点。模板顶部的表头对应 JIRA 问题字段的英文名，常见的有summary（标题）、description（描述）、issuetype（问题类型）、priority（优先级）、component（组件）、labels（标签）等。下载后用记事本打开确认一下编码，用 Excel 打开会出现后续章节提到的编码坑，这里先记下：模板默认是 UTF-8 编码。
准备 CSV 时有三个最基础也最关键的规则。第一，标题（summary）列不建议为空，JIRA 创建问题时标题是硬性要求，这一列留空大概率被跳过并在结果回执里标注失败。第二，问题类型（issuetype）列建议填中文名称而不是内部 ID，比如“任务”“缺陷”“需求”，插件在导入时是通过名称解析到具体类型 ID 的，填数字 ID 反而容易因为实例差异而解析失败。第三，日期列只接受两种格式：yyyy-MM-dd和带时间的yyyy-MM-dd HH:mm:ss，不要用 Excel 默认的yyyy/M/d，否则插件解析日期时会把月份和日期颠倒。
summary,description,issuetype,priority,component,labels 登录页按钮错位,首页登录按钮在 1080p 分辨率下遮挡输入框,缺陷,高,Web端,前端;UI 注册接口超时,压力测试下注册接口 P99 超过 3s,缺陷,中,服务端,性能这是一份最小可用 CSV。字段含义拆开看：summary是必填标题，description是描述，issuetype写中文名，priority写“高/中”这样的优先级关键词，component对应项目组件名，labels支持用分号分隔多个标签。注意这里的分号分隔是插件常用的写法，跟 JIRA 界面里逗号分隔的风格不同，以模板里标注的分隔符为准。
2.3 上传后的导入配置：字段映射、日期格式与打包逻辑
CSV 上传后进入“字段映射”步骤，这是整条链路里最需要仔细核对的一环。插件会把 CSV 表头与 JIRA 字段做一一对应，如果模板是你自己另做的而不是下载的，这里就会出现“未映射”的字段列，需要手动从下拉列表里选择对应关系。系统字段的映射比较简单，自定义字段则麻烦一些，常见做法是先把 CSV 的表头名字改成模板里的标准字段名，再上传，这样就省去了手动映射的环节；如果坚持用自定义表头，也可以在映射界面逐列指定。
日期格式在这个页面里要单独确认一次。插件会询问“CSV 中的日期使用哪种格式”，这里给出的选项一般包含 ISO 格式、带斜杠的美式格式、带中文年月日的格式。你之前在 Excel 里填的日期即使看起来正常，这里选错了照样导入失败。选择的原则很简单：以 CSV 文件里实际存储的文本为准，而不是以 Excel 表格里显示的样子为准。
导入方式有两种：直接创建和先预览后创建。我一般会先跑预览，插件会把 CSV 每一行解析出的字段值展示成表格，红色标注的是必填缺失或格式非法的单元格。预览无误后再点“创建”。真正执行时，插件会逐行调用 JIRA 内部的创建接口，每行结果为一条独立记录，最终生成一份“创建回执”汇总成功和失败的数量及原因。这个回执建议每次都下载存档，尤其是批量建几百条的时候，后面对账就靠它。
3. 把 CSV 字段安全送到 JIRA：映射规则与校验的隐藏规则
3.1 内置字段与自定义字段的映射办法
内置字段的映射相对简单，因为插件内部已经为 JIRA 的标准字段建好了解析器，但自定义字段就需要额外操作。在 2.3 节的映射页面里，自定义字段的处理逻辑是两步：先把 CSV 表头绑定到“自定义字段（名称）”，再在下拉列表里选择具体的自定义字段。如果项目里存在多个同名自定义字段（不同上下文中很常见），下拉列表会带上上下文名称或字段 ID 来区分，一定要选对。
这里有个从实践中得来的结论：名称相同的自定义字段是批量导入最容易踩的隐性冲突。某个项目里有个“版本号”字段，研发侧和测试侧各建了一个，名字一模一样，只是上下文范围不同。用户上传 CSV 时只看到“版本号”三个字，随手选中第一个，结果数据全写进了另一个上下文。排查才发现下拉列表里那两个选项后面的括号备注不同。建议管理员在字段管理里给同名自定义字段加上区分前缀，或者至少在批量导入前确认一次字段所属上下文。
3.2 日期、单选、用户、附件：四类值进 JIRA 的格式要求
日期列前面已经提过格式，这里补充一个细节：插件对日期列的空值容错率较高，空着会跳过，但填了非法值则整行失败，因为 JIRA 接口要求日期类型字段必须传合法值。日期里带时间时，时区按 JIRA 服务器时区解释，不随用户本地时区变化，跨时区团队协同录单时要注意。
单选字段（下拉列表）和单选按钮字段，CSV 里填的是选项的显示名称，不是选项 ID 或顺序号。这个逻辑对新手容易误解，因为在数据库层面 JIRA 存的是 option id，但插件做了名称到 ID 的解析。需要注意的是，如果同一个选项在字段配置里存在同名的两个值（不常见但会发生），解析器会取第一个匹配项，且不会报错。用户字段（经办人、报告人）支持填用户名或显示名，两者插件都能解析。填邮箱则不一定可靠，因为部分旧版本 JIRA 的 user 解析器不认邮箱格式，会直接报“用户不存在”。
附件列是比较特别的存在。模板里附件的填写方式是：多个附件之间用管道符|分隔，每个附件可以带完整本地路径，也可以只给文件名。插件执行创建时，会读取 JIRA 服务器本地磁盘上的文件，而不是读取用户本机的文件。这意味着用户不能指望把自己的本地文件路径填进去就能上传——要么文件已经放在服务器某个共享目录上，要么先手动上传到 JIRA 的临时区域。这个认知不到位，附件列基本是废的。
summary,description,issuetype,duedate,assignee,attachment 服务器磁盘告警,生产环境 /data 分区使用率 92%,任务,2025-06-30,zhangsan,/tmp/server-disk-check.log|/tmp/disk-usage-report.pdf这份 CSV 展示了日期、经办人、附件的组合用法。duedate用的是yyyy-MM-dd格式，assignee填用户名，attachment里两个文件都是服务器本地路径，管道符分隔。逻辑说明：插件逐字段解析时，日期列先按预设格式解析成 Java 的 Date 对象再传给创建接口；经办人解析为 JIRA 的 user 对象；附件列则按管道符拆分后逐个确认文件存在，文件缺失时该行会被标记为失败而不会影响其他行。
3.3 一次建多少条：拆分阈值与接口频率的现实边界
批量创建听起来是“一次全导入”，但插件在实际执行时并不建议单次尝试导入超过 500 条。这里有两个现实约束：一是 JIRA 自身的接口在短时间高并发创建时会触发限流或负载告警，尤其是 Data Center 模式下各节点要同步索引，大批量写入会导致索引延迟和页面查询卡顿；二是插件的回执机制会对每一条创建结果做状态回写，行数太多时回执生成时间会明显拉长，用户体验上像是“卡死了”。
常见做法是把大 CSV 拆成多个小批次上传。比如 2000 条拆成 5 批，每批 400 条，批次之间间隔几分钟再执行。如果单批超过 800 条且执行过程中出现超时，插件通常不会回滚已创建成功的行，而是以“部分成功”收尾，回执里能看到哪些行成功了哪些行失败了。失败的行的原因多为字段校验不通过或临时性接口异常，修正后单独用一个小 CSV 补传就行，不需要整个批次重跑。这一点很重要——重跑整个大文件会把已经成功的行重复创建一遍，造成重复工单。
4. 批量建单避坑实录：四个高频翻车点与排查路径
4.1 现象：CSV 上传后只有一条成功，其余全部卡在“待处理”
某次我协助一个项目组导入 120 条硬件报修记录，结果回执里只有第一条是成功，其余 119 条全部是“待处理”状态，且页面没有给出具体错误信息。排查后发现 CSV 表头第一行末尾多了一个空格，Excel 保存时自动加了不可见字符，导致插件解析表头时第一列的名称匹配到了，其余列全部匹配不上，字段映射大面积落空，数据无从写入。解决方法是检查 CSV 原始文本，把表头里的空格、换行符清干净，用记事本另存为 UTF-8 编码后重新上传。这个案例以后，我每次处理新 CSV 都先用文本编辑器打开看一遍表头，而不是直接信 Excel 的预览。
4.2 现象：Excel 保存的 CSV 中文全部乱码
最常见的坑没有之一。Windows 下的 Excel 默认用 GBK/ANSI 编码保存 CSV，而插件默认按 UTF-8 读取，结果就是中文标题、描述全部变成“锟斤拷”。解决方法是：在 Excel 里另存为 CSV 时选择“CSV UTF-8（逗号分隔）”，不要选默认的“CSV（逗号分隔）”。如果文件已经生成了，用记事本打开后另存为 UTF-8 编码也可。老手会直接在模板里用脚本生成 CSV，绕开 Excel 的编码问题。
# 批量检查 CSV 文件编码（Linux/macOS 环境） file -i issues.csv # 期望输出：issues.csv: text/plain; charset=utf-8 # 如果输出 charset=unknown-8bit 或 charset=iso-8859-1，说明编码不对这条命令的作用是快速确认 CSV 的文件编码声明。file -i会读取文件头部字节特征判断字符集，是排查乱码问题最直观的手段。参数说明：-i表示输出 MIME 类型信息。如果发现编码不对，可以用iconv -f GBK -t UTF-8 issues.csv > issues-utf8.csv做一次转码，转完后建议再用file -i复查一遍。
4.3 现象：项目 key 缩写不存在的告警
插件在导入时要求 CSV 里包含项目信息，有的版本支持在配置页面选择目标项目，有的版本依靠 CSV 里的project key列。用户填写了如TESTPROJ这样的缩写，插件却报“project key not found”。排查要点：项目 key 严格区分大小写，且不允许带空格和特殊字符；JIRA 界面里显示的项目 key 是全大写，但插件解析时没有做大小写归一化处理，填小写就会失配。另外如果后续项目做过迁移，旧 key 可能已经在后台被注销，界面里看得到历史项目名但 key 已经变了。解决方法是到项目管理的“项目详情”里复制真实的 key，不要凭记忆手打。批量导入前用小 CSV 先测 3 条，确认 key 解析正常再放全量数据。
4.4 现象：自定义字段值对不上，页面端手填却正常
这类问题最让人头疼，因为表现是“部分行成功，部分行失败”，失败原因提示“field value not valid”。原因通常是自定义字段带上下文校验规则，比如只允许某个项目中使用，或者设置了正则校验，CSV 里填的值不符合规则。另一个隐藏因素是：自定义字段的类型是数字或浮点，CSV 里填了“1,000”这样的带千分位格式，插件按纯文本提交给 JIRA，底层字段校验不认。解决方法是把值格式化成 JIRA 能接受的纯数字格式，先查字段配置里的校验规则，再检查 CSV 单元格是否混入了 Excel 的格式化痕迹。
4.5 诊断不好使时：打开插件运行日志看真实报错
页面提示“请联系管理员”或只有笼统的“导入失败”时，不要反复重新上传碰运气。JIRA 的运行日志目录下，插件一般会输出独立的日志文件或混杂在atlassian-jira.log里。用日志追踪插入失败的真正异常栈：是数据库连接问题还是字段解析问题，一目了然。
# 查看插件相关日志（Linux 环境示例） grep "bulk-create" /var/log/atlassian/jira/atlassian-jira.log | tail -n 50这段命令从全局日志里过滤插件名相关记录，tail -n 50只保留最近 50 条，避免输出刷屏。参数说明：日志路径按实际部署位置调整，Windows 部署一般在安装目录的log子目录下。日志里常见的报错有Field 'xxx' does not exist（字段映射问题）、Invalid date format（日期格式问题）、User not found（用户名解析失败），按信息定位对应列修改即可。
5. 让批量创建再顺一步：模板预填、字段快照与收尾三件套
5.1 模板属性：把项目 key、组件、经办人固定成你的习惯值
重复性最高的批量导入场景，往往是同一个项目、同一类问题、同一拨经办人。每次都在 CSV 里重复填这些列，既繁琐又容易出错。插件支持“模板属性预设”，也就是在插件的设置页面里保存一组默认值，之后每次上传 CSV，这些列会自动回填，CSV 里可以不包含这些列。我一般会为每个项目组预设好：目标项目 key、默认问题类型、优先级、组件名。其中经办人我不会预设，因为不同批次的经办人变化较大，预设了反而容易写错。
具体操作：进入插件设置页，找到“默认字段值”区域，逐项填写后保存。下次导入时会看到页面顶部提示“已应用模板属性”，确认无误后执行即可。这个功能的价值在于把“每次都要配置的公共参数”从用户心智里移除，让用户只关注每个 CSV 行里真正不同的数据。
5.2 数据核对三件套：回执、列表视图快速扫描、失败重试
创建完成不等于工作完成。我给自己定的收尾流程是固定三件事：下载回执 CSV、去 JIRA 的搜索结果页核对数量、修正失败行重试。回执 CSV 里每一行会标注 issue key 或失败原因，这是对账的第一手资料。列表视图快速扫描用 JQL 按项目和时间过滤出刚创建的工单，核对标题前几个字是否符合预期，防止有大量行创建到了错误项目。
project = TESTPROJ AND created >= "2025/06/01 10:00" AND created <= "2025/06/01 11:00" ORDER BY created DESC这条 JQL 限定了项目、创建时间范围，专门用来核对刚批量创建的工单。逻辑说明：created范围精确到时分，能圈定一次导入的窗口；排序按创建时间倒序，最新创建的工单排在最前。核对时重点看两点：数量是否与回执成功数一致，标题列是否都是本批次的内容。确认无误后再把回执存档到项目目录，后续有人质疑工单来源时直接甩回执。
5.3 从一次事故学会的收尾习惯
有一次批量导入接近 700 条工单，回执显示 698 条成功，2 条失败。当时赶进度，没仔细看失败原因，直接修改数据重试了那 2 条，收工走人。第二天项目组反馈有 4 条重复工单，追溯后发现最初 698 条成功里混进了 2 条其实是“重复提交”的情况——第一次执行时接口超时但实际已创建成功，回执显示失败，我重试又建了一次。从那以后，我每次遇到失败行都不直接重试，先按标题去 JIRA 搜索确认该工单是否已存在，存在就跳过，不存在再创建。批量创建类操作最怕的就是“重跑”和“重试”，它们才是重复工单的真正来源。这份插件本身很靠谱，坑大多出现在 CSV 准备和收尾核对上，把这两步做成固定习惯，这个工具就会成为团队里最实用的效率件。希望帮到你。
本文还有配套的精品资源，点击获取
