การเผยแพร่ไปยัง npm และการกำหนดเวอร์ชันเชิงความหมาย

ก่อนเผยแพร่ ให้เรียกใช้ npm publish --dry-run ทุกครั้ง คำสั่งนี้จำลองการเผยแพร่โดยไม่อัปโหลดสิ่งใดจริง แสดงให้เห็นอย่างชัดเจนว่าไฟล์ใดจะถูกรวม ขนาดของไฟล์ และเนื้อหาของไฟล์บรรจุแพ็กเกจ คำสั่งนี้ช่วยตรวจจับข้อผิดพลาดที่พบบ่อย เช่น การรวมไฟล์ต้นฉบับโดยไม่ตั้งใจ หรือไม่มีไดเรกทอรี dist

ควบคุมสิ่งที่จะเผยแพร่โดยใช้ฟิลด์ files ใน package.json: "files": ["dist", "README.md"] แนวทางการระบุรายการที่อนุญาตนี้ปลอดภัยกว่า .npmignore ซึ่งเป็นรายการปฏิเสธและอาจทำให้ไฟล์ที่มีข้อมูลละเอียดอ่อนรั่วไหลได้หากคุณลืมเพิ่มไฟล์เหล่านั้น โปรดรวม dist คำประกาศชนิดข้อมูล และเอกสารไว้เสมอ อย่ารวม src การทดสอบ หรือ node_modules

แพ็กเกจ npm ใช้การกำหนดเวอร์ชันตามความหมาย (semver): MAJOR.MINOR.PATCH ให้เพิ่ม MAJOR เมื่อมีการเปลี่ยนแปลงที่ทำให้การใช้งานเดิมเสียหาย เช่น การนำพร็อพออกหรือเปลี่ยนลายเซ็นของ API ให้เพิ่ม MINOR เมื่อเพิ่มความสามารถใหม่ที่ยังเข้ากันได้กับเวอร์ชันก่อนหน้า เช่น คอมโพเนนต์ใหม่หรือพร็อพใหม่ที่เป็นตัวเลือก ให้เพิ่ม PATCH เมื่อแก้ไขข้อบกพร่องโดยยังเข้ากันได้กับเวอร์ชันก่อนหน้า เวอร์ชัน 0.x.x ถือว่ายังไม่เสถียร จึงอาจมีส่วนใด ๆ เปลี่ยนจนใช้งานไม่ได้

ตัวระบุก่อนเผยแพร่ใช้บ่งบอกว่าเวอร์ชันนั้นยังไม่พร้อมสำหรับใช้งานจริง: 1.0.0-alpha.1 สำหรับรุ่นทดลองระยะแรก 1.0.0-beta.2 สำหรับรุ่นที่ความสามารถครบถ้วนแล้วแต่อาจยังมีข้อบกพร่อง และ 1.0.0-rc.1 (รุ่นตัวเลือกสำหรับเผยแพร่) สำหรับรุ่นที่พร้อมเข้าสู่การทดสอบขั้นสุดท้าย ให้เผยแพร่รุ่นก่อนเผยแพร่ด้วย npm publish --tag beta เพื่อไม่ให้กลายเป็นรุ่นเริ่มต้นที่ผู้ใช้ติดตั้ง

Changesets เป็นเครื่องมือมาตรฐานสำหรับจัดการการกำหนดเวอร์ชันของแพ็กเกจและบันทึกการเปลี่ยนแปลงในไลบรารีคอมโพเนนต์ ขั้นตอนการทำงานมีดังนี้ ผู้มีส่วนร่วมเรียกใช้ yarn changeset add เพื่อบันทึกสิ่งที่เปลี่ยนแปลงและประเภทการเปลี่ยนแปลง (major/minor/patch) ระบบ CI เรียกใช้ yarn changeset version เพื่อปรับเพิ่มเวอร์ชันของแพ็กเกจ จากนั้นขั้นตอนการเผยแพร่เรียกใช้ yarn changeset publish เพื่อเผยแพร่ไปยัง npm

Changesets จะสร้างและดูแล CHANGELOG.md โดยอัตโนมัติ โดยอ้างอิงจากไฟล์ Changesets ที่ผู้มีส่วนร่วมส่งเข้าไปในคลัง แต่ละรายการประกอบด้วยหมายเลขเวอร์ชัน วันที่เผยแพร่ และคำอธิบายการเปลี่ยนแปลง วิธีนี้สร้างประวัติของทุกเวอร์ชันที่มนุษย์อ่านเข้าใจได้ โดยไม่ต้องดูแลบันทึกการเปลี่ยนแปลงด้วยตนเอง

semantic-release เป็นเครื่องมือกำหนดเวอร์ชันแบบอัตโนมัติทั้งหมด โดยกำหนดเวอร์ชันถัดไปจากข้อความคอมมิตตามรูปแบบ (feat: → minor, fix: → patch, BREAKING CHANGE: → major) เครื่องมือจะปรับเพิ่มเวอร์ชัน สร้างบันทึกการเปลี่ยนแปลง และเผยแพร่ไปยัง npm ทั้งหมดนี้เริ่มทำโดยระบบ CI เมื่อผสานเข้ากับ main ไม่ต้องจัดการเวอร์ชันด้วยตนเอง

แพ็กเกจที่ไม่มีขอบเขต (my-component) จะเป็นสาธารณะเสมอ แพ็กเกจที่มีขอบเขต (@myorg/my-component) จะมีค่าเริ่มต้นเป็นแบบจำกัด (ส่วนตัว) หากต้องการเผยแพร่ให้เป็นสาธารณะ ให้ใช้ npm publish --access public แพ็กเกจแบบจำกัดต้องใช้บัญชี npm แบบชำระเงินหรือองค์กร โปรดยืนยันการตั้งค่าสิทธิ์ก่อนเผยแพร่ครั้งแรก

การยืนยันแหล่งที่มาของ npm จะเชื่อมโยงแพ็กเกจที่คุณเผยแพร่เข้ากับคอมมิต git เฉพาะรายการด้วยวิธีที่ตรวจสอบได้ เปิดใช้ความสามารถนี้ด้วย npm publish --provenance ใน GitHub Actions ผู้ใช้สามารถตรวจสอบได้ว่าแพ็กเกจที่ติดตั้งสร้างมาจากคอมมิตต้นฉบับที่ตรงกันทุกประการกับรายการที่แสดงบนหน้าทะเบียน npm วิธีนี้ช่วยยกระดับความปลอดภัยของห่วงโซ่อุปทานได้อย่างมาก

เมื่อเวอร์ชันมีข้อบกพร่องร้ายแรงหรือมีการเปลี่ยนแปลงที่ทำให้การใช้งานเดิมเสียหาย ให้เลิกใช้งานเวอร์ชันนั้นด้วยคำสั่ง npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4" npm จะแสดงคำเตือนว่าเลิกใช้งานแล้วแก่ผู้ที่ติดตั้งเวอร์ชันดังกล่าว การดำเนินการนี้ไม่ได้ลบเวอร์ชันนั้นออกไป เพราะโดยค่าเริ่มต้น npm จะไม่ลบเวอร์ชันที่เผยแพร่แล้ว แต่จะแจ้งเตือนให้ผู้ใช้อัปเกรด

แพ็กเกจแบบมีขอบเขตใช้รูปแบบ @scope/package-name โดยทั่วไปขอบเขตจะเป็นชื่อผู้ใช้ npm หรือชื่อองค์กรของคุณ แพ็กเกจแบบมีขอบเขตช่วยให้เห็นได้ชัดเจนว่าใครเป็นผู้ดูแลแพ็กเกจ และป้องกันชื่อซ้ำกับแพ็กเกจที่ไม่มีขอบเขต โปรดใช้แพ็กเกจแบบมีขอบเขตสำหรับแพ็กเกจส่วนตัวและแพ็กเกจโอเพนซอร์สที่เกี่ยวข้องกับองค์กรของคุณ

ใช้ npm publish --dry-run เพื่อดูตัวอย่างก่อนเผยแพร่ และใช้ฟิลด์ files เพื่อควบคุมสิ่งที่จะเผยแพร่ การกำหนดเวอร์ชันตามความหมาย: MAJOR สำหรับการเปลี่ยนแปลงที่ทำให้การใช้งานเดิมเสียหาย MINOR สำหรับความสามารถใหม่ และ PATCH สำหรับการแก้ไข รุ่นก่อนเผยแพร่ใช้แท็ก -alpha/-beta/-rc Changesets ช่วยทำให้การกำหนดเวอร์ชันและการสร้าง CHANGELOG เป็นอัตโนมัติสำหรับไลบรารีที่ทำงานร่วมกัน semantic-release ทำให้กระบวนการจากคอมมิตตามรูปแบบเป็นอัตโนมัติ เปิดใช้ --provenance เพื่อความปลอดภัยของห่วงโซ่อุปทาน และเลิกใช้งานเวอร์ชันที่มีข้อบกพร่องด้วย npm deprecate