從零做一個前端開源項目

來自專欄 猿論

前言

每個程序員都應該有自己的 github 賬號，並貢獻自己的代碼

本文將像您介紹，如何從零做一個前端的開源項目。如果您對 github 和開源不熟悉，又想開始自己的開源項目，可以通過閱讀本文來入門。

另外，本文將會錄製成免費的視頻教程，文中如果有寫的不詳細的，視頻中肯定會詳細講解。待錄製完之後，我會把鏈接貼在這裡。

目錄

由於本文內容較多，先列一下目錄供參考。

• 什麼是開源？
• 為何做開源？
• 做什麼？
• 註冊賬號
• 搭建開發環境
• 提交代碼
• 創建官網
• 如何宣傳？
• 持續迭代
• 總結

什麼是開源？

您可能有很多次打開 github 去查閱下載一些項目的源碼，但是您有沒有總結過，開源項目到底是什麼？

我與開源

我是開源編輯器 wangEditor 的作者（歡迎去 star），這個項目已經做了有近 4 年了，目前積累了 4.5k star（現在是 2018.5）。4 年時間，我一直未間斷維護升級，其中還經歷了 2 次大型的重構，積累了一些經驗和教訓。接下來我將根據自己的經歷，來為大家分析開源。

開源項目包含什麼

開源軟體並不是只是一堆源代碼，如果你仔細分析或者有親身體會的話，包含內容還是比較多的。我總結了以下內容：

• 源碼
• 文檔，如二次開發文檔和用戶使用文檔
• 開發環境，告訴二次開發者如何搭建和運行代碼
• 允許他人貢獻代碼，而不是僅僅給別人閱讀源碼的許可權
• 問題，用戶提問，維護者答覆，問題共享（而不是私聊）
• 問題列表和升級計劃，記錄當前問題，以及何時解決、何時升級

其他配套設施

要做成一個成熟靠譜的開源軟體產品，除了以上源碼相關的方面，還需要以下配套的設施，才能完備。

• 官網，如 wangEditor 官網
• 文檔，可以和官網整合在一起
• 問答社區，wangEditor 的問題社區就用了 github issue
• 及時交流社區，即 QQ 群、微信群

為何做開源？

做開源不掙錢，這是確定的，但是為何要做開源，而且那麼多人堅持做開源呢 —— 他們不是完全為了興趣愛好，完全下班沒事兒干。人只要付出勞動、付出努力，都是奔著目的性去的，有興趣的原因，但是能讓自己持之以恆做下去的，肯定不是興趣。

其實這個問題很簡單，就像看書不掙錢（買書還花錢呢），但是為何要看書呢？因為大家都知道看書能提高自己的知識面和能力。而做開源也有相似的想過，只不過很多人沒接觸過不知道而已。我總結了如下幾個理由：

• 全面提高編程能力。 你需要從 0 打造，每部分代碼都需要自己負責，不像在公司中的一顆螺絲釘。
• 提高自己的社區知名度。 github 上的 star 能間接的反應你的身價，它能讓你得到業內認可。業內同行認可了，做啥事兒都好做，如內推工作。
• 鍛煉自己的產品意識。 因為做開源做的是產品，不再是單純的技術活，UI、運維、推廣、收集反饋、甚至成本預算，你都得考慮。
• 技術范兒、極客精神。 作為一名程序猿，能業餘打造一款開源產品是一件很帥的事情，滿足自己的虛榮心。

有了充分的理由，那就開干！

做什麼？

邁出第一步

這是做開源要想到的第一件事情，很多想做開源的同學，到這一步就想不下去了。還有同學，一上來就定位太高，做著做著發現根本做不出來，就提前放棄。做什麼，看似簡單的問題，但是很重要的一步。

不做什麼

一些早期就知名的開源作品，很多都是因為作者在工作中遇到一個需求，而這個需求目前還沒有開源產品去滿足，因此自己做一個。但是對於我們大眾基層程序猿，天天寫業務代碼，重複勞動，你遇到這種需求的概率不是特別大。因此，這個方面就不在繼續往下討論了。

想要知道做什麼，你就得先明白你做開源的一些期望，然後再去想做什麼。我總結了兩點：

• 要快速做出第一版，至少能用。後面再慢慢迭代升級。
• 要能方便的推廣使用，最好是 0 成本使用。

即做出來，推出去，要快。即，你做的快，別人用的也快。按照這種期望往下想，首先你能排除不做什麼：

• 大型的框架，如做一個 UI 框架。 短期做不完，使用成本高
• 模擬成熟輪子，如在造一個 jQuery 。 有成熟方案，用戶不會換
• 小眾的東西。 基本沒人用
• 沒有特色，100% 的模仿。 用戶沒有更換的理由

做什麼

排除以上這些，還剩下的範圍就不做了，我推薦做開源產品的方向：

• 小而精的工具。 開發快，使用成本低。
• 要有特色，哪怕是一個。 要和別人不一樣，差異化競爭。
• 一定要大眾，50% 以上的開發人員都會用到
• 避開已經被成熟產品壟斷的領域。 你就不要去跟 jQuery vue React 競爭了。

例如，前幾天 is-odd 在知乎鬧的沸沸揚揚，這個庫就是判斷奇數偶數，只不過考慮了各種數據類型的轉換。但是你看它的 weekly downloads 數量多大。

下面列舉幾個我認為比較合適做開源的例子：

• cache 工具（緩存工具，整合 localStorage，以及合理的內存銷毀機制）
• query2json，解析 url 參數為 json 格式
• 移動端列印 console.log ，方便移動端輸出內容

其他符合上述條件的，根據自己當前的情況，大家可以自由發揮。最後，選擇哪個不重要，重要的是你選擇出來了。因此，如果你實在沒有合適的選擇，不如就從我舉例中選擇一個，抓鬮也行。選擇出來，你就可以繼續往下做了，否則你一直都在糾結。

本文將做什麼

好了，本教程就確定要做一個 cache 工具，取一個性的名字，不和現有的重複（是否重複，去 github 一搜便知），叫做fast-cache。

註冊賬號

注意，你如果現在已經有了 github 賬號，也不好忽略這一章的內容，很重要！

你一旦註冊一個 github 賬號並且去做開源產品，那你就要作為一個個人品牌持續運營下去，不能隨便改名字。因此註冊賬號時一定要慎重考慮，不能隨便弄一個，做一段時間又想改。

組織還是項目

首先，你要明確你即將註冊的賬號是專門針對一個產品（即項目賬號）還是將運維多個產品（即組織賬號）？

例如，facebook 就是 github 中的組織賬號，其下有很多開源產品，如 react 和 hhvm 等。而 rollup 就是 github 中的項目賬號，其下就一個項目 rollup ，其他的項目都是一些附件插件。

對於我們個人開發者，我推薦註冊項目賬號，即以你項目的名稱取個賬號的名字。這樣還有一個好處，就是後面講到官網的時候，你可以用更短、更好記的官網地址。例如，如果不自己申請域名、假設伺服器（即不花一分錢）的情況下，以上例子中他們的官網有區別。

• rollup 的官網地址將是 rollup.github.io ，很短；
• react 的官網地址只能是 facebook.github.io/react，多了一級目錄；（注意是不申請域名、不花錢的情況下）

最後，我選擇項目賬號，因此我需要註冊的賬號是 fast-cache 。

註冊賬號

我們分別要去 github 和 npm 註冊以 fast-cache 為用戶名的賬號，註冊過程就不寫了，都是傻瓜式操作。需要注意的是，如果被牆，自己想法辦科學上網。

創建項目

登錄 github ，點擊右上角的「+」可看到新建項目的鏈接，或者直接訪問 https://github.com/new 。創建項目如下圖所示，注意圖中紅框部分。

創建完成之後，通過 https://github.com/fast-cache/fast-cache 即可訪問到項目的主頁，這是你就已經有了自己的開源項目了。

添加 ssh key

ssh key 就是連接你的電腦和 github 伺服器的一把鑰匙，只有添加成功了才能把你本地的代碼提交到 github 伺服器。

如果你是 mac os 系統，運行 ssh-keygen 即可一步一步生成 ssh key ，然後運行 pbcopy < ~/.ssh/id_rsa.pub 即可拷貝下來，等著粘貼。windows 系統用戶，自己百度搜索 github ssh key 即可找到相關介紹文章，跟著做就行了。

在 github 個人中心的設置界面，能找到 SSH and GPS keys 菜單欄，或者直接訪問 https://github.com/settings/keys 。頁面中點擊右側「new ssh key」按鈕即可添加 ssh key ，把剛才的內容粘貼過來添加上就行了。

下載代碼

進入 github 項目主頁，複製 git 地址（注意選擇 use ssh ，不要 use https ），如下圖

複製下來的內容應該是 git@github.com:fast-cache/fast-cache.git ，然後你選擇一個合適的文件夾或目錄，執行下載命令。

git clone git@github.com:fast-cache/fast-cache.git

下載完畢，進入代碼目錄，運行如下命令修改當前 git 的用戶名和郵箱，改成和當前 github 用戶名和註冊郵箱一致。

cd fast-cachegit config user.name fast-cachegit config user.email fast-cache@github.com

最後，隨便修改一下 README.md 文件的內容，然後提交，看能否成功？成功了就說明剛才的ssh key 生效了。

git add .git commit -m "first update"git push origin master

搭建開發環境

初始化

進入項目目錄，然後命令行運行 npm init ，按照提示進行初始化即可。提示中的信息，能寫的都寫上，別隨意忽略了。初始化完成之後，項目根目錄下會有 package.json 的文件。

規範版本號

打開 package.json 文件，將版本號定義為 "version": "0.0.1" 。以後我們每次正式提交代碼，版本號都不一樣。版本號分三級，分別為：

• 一級，重構版本
• 二級，重大功能改進
• 三級，小升級或者 bug 修復

為何從 0.0.1 開始？因為 0.x.x 可以認為是非正式版本、測試版，而從 1.x.x 開始，就是正式發布的版本了。

規範一級目錄

項目的一級目錄要提前規範好，最起碼一些常用的目錄要提前訂好留用，不能亂來。例如：

• src - 源代碼
• release - 發布結果
• test - 單元測試用例
• doc - 文檔
• example - 示例

構建工具

這部分比較獨立，內容也比較多，就不詳細講了，用最常用的 webpack 做一個簡單演示吧。

安裝插件 npm i babel-core babel-loader babel-polyfill babel-preset-es2015 babel-preset-latest webpack webpack-cli --save-dev 。

項目根目錄下創建 .babelrc 文件，內容如

{ "presets": ["es2015", "latest"], "plugins": []}

項目根目錄下創建 webpack.config.js 文件，內容如

module.exports = { entry: ./src/index.js, output: { path: __dirname, filename: ./release/bundle.js }, module: { rules: [{ test: /.js?$/, exclude: /(node_modules)/, loader: babel-loader }] }}

最後，修改 package.json 中的 scripts ，增加 "release": "webpack" 。然後命令行運行 npm run release ，就可生成 release 的內容。

運行示例

release 的內容已經發布出來了，還要運行起來，最簡單的方式，在example創建test.html，然後引用 release 的內容。

<!DOCTYPE html><html><head> <meta charset="UTF-8"> <title>example</title></head><body> <p>example</p> <script src="../release/bundle.js"></script></body></html>

為何規範化運行，可以修改 package.json 中的 scripts ，增加 "example": "http-server -p 8880" 。然後命令行運行 npm run example ，瀏覽器訪問 http://localhost:8880/example/test.html 。

規範 git 分支

至少要存在兩個分支，master 和 dev ， dev 是開發中的代碼。當然，你可以規範更多的分支，例如 next fix-bug 等，但是注意一個原則 —— 用不到的就先不要規劃。

完善 README.md

README.md 是開源項目的一張臉，用戶的第一印象。必須包含以下內容：

• 產品簡介（此處要突出特點，打差異化競爭）
• 產品安裝和下載
• 快速使用（詳細的使用文檔或者二次開發文檔，外鏈即可）
• 交流提問區
• 關於作者（放你的博客鏈接，和收款二維碼）

最後，把以上完成的工作，都提交到 github 中。

提交代碼

寫代碼

具體寫什麼代碼不是本文的重點，你盡情的根據自己的項目來寫自己的代碼就是了。記得一定要使用編碼規範的工具，例如 es-lint 等，否則經過長時間的維護，必然留坑。

寫文檔 & 寫測試用例

注意，文檔和測試用例對於一個開源產品來說非常重要！非常重要！非常重要！而且，文檔和測試用例本身就是代碼不可分割的一部分。

如何寫測試用例，需要用到其他工具，內容也相對獨立，這裡就不介紹了，自己去查一查吧。再次強調，測試用例很重要！！！

在寫文檔之前，還需要準備其他的工具。定位到項目目錄下，npm i gitbook-cli -g 安裝 gitbook ，然後創建 SUMMARY.md ，內容如下：

# Summary* [項目介紹](README.md)* [使用文檔](doc/use/README.md) * [使用1](doc/use/use1.md) * [使用2](doc/use/use2.md)* [二次開發](doc/dev/README.md) * [開發1](doc/dev/dev1.md) * [開發2](doc/dev/dev2.md)

其實一看這個文件內容就知道，這是一個文檔的目錄，你可以根據自己項目的需要重新定義這個目錄。需要注意的是，第一行 * [項目介紹](README.md) 對應的是已經存在的 README.md 文件。

運行 gitbook init ，會看到各個文件都被創建了，就可以完善各個文檔的內容。內容完成之後，運行 gitbook build 可以將 md 文件發布為 html 文件，默認放在 _book 文件夾。啟動了 npm run example 之後，可以訪問 http://127.0.0.1:8880/_book/ 查看效果。

最後，再次修改一下 README.md ，把文檔的鏈接加上

[如何使用](./doc/use/README.md) [二次開發](./doc/dev/README.md)

提交第一版代碼

首先，修改一下 .gitignore 文件，加上一行 _book ，把打包出來的文件忽略掉。然後用之前的方式提交到 github 的 master 分支，這裡不再贅述了。

接下來，創建 tag 並提交，代碼如下：

git tag -a v0.0.1 -m first commitgit push origin v0.0.1

提交之後，下載地址就有了 ， https://github.com/fast-cache/fast-cache/releases 這裡可以下載到各個版本的源碼。

最後要提交到 npm 上，能讓使用者通過 npm 進行安裝。首先，運行 npm add user 和 npm login 來登錄，根據提示將你之前註冊 npm 時的賬號、密碼、郵箱寫上就行了，問題不大。然後，在項目的根目錄運行 npm publish . ，此時問題來了！！！

運行之後報了 403 錯誤，剛才明明登錄成功了，不可能有許可權問題呀。後來一查才知道，原來 fast-cache 在 npm 中和其他項目重名了！！！沒辦法，只能改名，將 package.json 中的名稱改為 fast-cache-npm ，然後再發布就成功了。

發布之後，通過 https://www.npmjs.com/package/fast-cache-npm 就可以訪問 npm 項目主頁了。

注意，為項目取名時，一定要提前把名字在 github 和 npm 搜索一下，確認沒有重名才行！！！

升級代碼並提交

上述是第一次提交代碼的流程，下面簡述一下升級代碼之後的提交流程。在代碼開發階段的步驟總結如下：

• 來一個 dev 分支，不要在 master 分支開發
• 修改 package.json 版本號，按照之前既定的版本規則修改，不能亂改
• 修改代碼、文檔和測試用例
• 自測
• 將 dev 分支提交到遠程

代碼開發完成之後，提交的流程如下：

• 再次確認版本號，因為版本號非常重要
• 將 dev 合併到 master ，並提交 master 到遠程
• 創建 tag 並提交到遠程
• 提交到 npm

合併 pr

pr 即 Pull Request 的簡稱。

開源軟體最大的特色就是允許全世界的開發者都能為其貢獻代碼，你這個開源項目也不例外。其他人很有可能會通過 github 的 pr 為你的項目貢獻自己的代碼，到時候你既得欣然接受，又不能茫然接受。

其他人貢獻的 pr 可以通過 https://github.com/fast-cache/fast-cache/pulls 鏈接看到。對於每一個 pr ，如果你想合併，直接 merge 就好了（合併完之後，本地代碼要隨時更新一下）；如果你不想合併，留言說明然後關閉掉即可。

創建官網

我們通過 github pages 的機制即可免費創建項目的掛網，不用花一分錢。

創建項目

登錄 github ，創建一個名為 fast-cache.github.io 的項目，名字必須是這一個！！！然後下載到本地，即 git clone xxxx 。然後，進入項目目錄，新建一個 index.html ，然後隨便寫點什麼，例如 <h1>hello world</h1> ，提交到 github 遠程。

最後，訪問 fast-cache.github.io ，你就能看到剛才的內容了，最簡單的官網就這麼出來了。做到這裡，你應該知道 github pages 就是一個靜態頁面的伺服器，上傳相應的 html 就能顯示。

生成官網

此前用 gitbook 將文檔生成為 html 了，應該還記得。那麼我們現在重新運行 gitbook build 生成 html ，然後將所有的 html 拷貝到這裡來，全部提交上去，正式的官網也就出來了。

更新 README.md

記得要修改 README.md ，把官網的地址加進去。

如何宣傳

「酒香不怕巷子深」這句話在當代並不適用，特別是互聯網中。我在 N 年前看過一本創業公司老闆寫的研發項目管理方面的書，到現在就記住一句話 —— 「一個公司的核心競爭力，一是技術，二是營銷」。因此，雖然是一個簡單的開源項目，宣傳也是必須必要的。

宣傳和更新維護都是一個漫長的過程，作為屌絲賬戶的我們（不是 google facebook 等明星賬戶），能做的只能是堅持。

寫博客

首先，要圍繞著你做的產品功能來寫博客。例如針對 fast-cache ，我們可以寫類似這樣的博客。分體分兩類，第一類是相關的技術乾貨文章，第二類是產品介紹，應該以第一類為主。

• 總結如何做前端緩存
• 前端緩存的坑
• 預防前端內存泄露
• 前端緩存插件 fast-cache使用總結
• fast-cache 開發半年記
• ……

其次，要正確選擇發表的網站，我的建議是這樣的：

• 選擇一個地方作為你博客的唯一主頁，例如 github ，像創建官網一樣創建個人博客網站。
• 博客貼到各大博客網站，如掘金、知乎專欄、博客園。選擇三個流量較大的即可，不用到處亂貼。
• 博客內容要寫明白原文的鏈接，並寫明產權。
• 最好能找到一些媒體（如 InfoQ）或者大牛公眾號幫你轉發。

回答相關問題

去知乎、sf.gg 甚至是 stackoverflow 上面去搜索、關注與你產品相關的問題，積极參与回答。回答問題也有技巧：

• 字數只能多不能少。最好圖文並茂，還能講個笑話
• 回答要專業，經過親自測試，不要想當然的瞎猜
• 回答問題的最後，順便推廣自己的產品

口碑宣傳

所謂口碑宣傳就是讓用戶資源的幫助宣傳，那就需要把產品做好，那如何做「好」呢？

• 明確產品定位，有特色。做「T」型產品，差異化競爭。把一方面做好就行了，所有都做好不可能。
• 及時回復問題，定期更新升級，做好升級計劃，讓用戶看到產品在不管進步和變化。

持續迭代

主要來探討一下如何有效率的持續迭代，再不影響工作、生活的情況下。

統一問題收集區

這一點非常重要！！！ 因為：

• 你沒有那麼多精力去很多個平台回復問題
• 你沒有那麼多時間天天盯著 QQ 群解答問題
• 問題應該被集中起來，供使用者反覆查閱

例如 wangEditor 的問題收集區主要集中在 github issue 列表，其他的地方的提問直接忽略。還有一點要特別注意，問題應該本分享，而不是私聊，因此如下提問方式直接忽略：

• QQ 群提問和 QQ 私聊提問（或微信）
• 私信提問
• 郵件提問

回顧我前幾年剛做開源的經歷，一開始你和使用者都會非常不習慣這種方式，特別是那些討厭的伸手黨。剛開始進來的用戶直接 QQ 私聊或者群里 @ 你，讓你做他們的技術客服，隨叫隨到，這種人你一定要堅持不理會，然後引導他們去 github 提交 issue 。慢慢的，你的社區和 QQ 群人多了，大家都知道這個套路，再有新人進來會自動被引導到 github 中提交 issue 。

定期答覆和升級

讓別人自願、積極的去提交 issue 的前提是你能及時的答覆。根據我的經驗，給你以下建議：

• 定期回復 每天（下班或者上班之前）看看 github issues 然後先答覆，臨時無法搞清楚的就回復「周末時看下再答覆」。這樣每天大約花費 5-15 分鐘即可，出去抽根煙的功夫。最後，需要修改的問題，先記錄下。
• 定期升級 每周拿出 2 個小時（隨便一個晚上或者周末時間）把記錄下的問題，按照優先順序高低順序修復。就 2 小時，改多少算多少，改不完下周再說。改完的問題要及時回復 issue 並 close 。每周 2 小時，對你這周的工作生活應該不會受到影響。

學會拒絕

當用戶慢慢增多，用戶會提出各種看似奇葩的需求，以滿足他們自己的使用需要。此時就需要你來分辨該需求是否應該被添加。我總結了以下判斷標準：

• 很多用戶都提過這個需求，即大眾需求
• 你自己判斷這個需求對大部分用戶都有用
• 該需求符合產品定位以及產品發展的方向
• 該需求能抹平和競品的差距，或者能和競品差異化競爭

符合以上要求的，可以加入升級計劃。不符合要求的，你一定要無情拒絕，此時不要做好人。

持之以恆

雖然每天十幾分鐘、每周兩小時看似不佔用太多時間，但是你要持之以恆的堅持一年、兩年、三年，你能做到嗎？

你做任何什麼事情，沒點持之以恆的態度，都做不成功。

總結

回顧一下本課程的重點內容：

• 做開源的意義。不是套話，你意識不到，肯定就做不下去；
• 開源項目是什麼。不僅僅是源碼。
• 做什麼。小而精，不要大而全。
• 怎麼做？
• 宣傳和持續迭代

作者：雙越

鏈接：https://www.imooc.com/article/28240

來源：慕課網

本文原創發佈於慕課網 ，轉載請註明出處，謝謝合作

推薦閱讀：

打造個人品牌 so easy ！_慕課手記

有獎徵文003期|程序員進階路上，哪本書你認為很不錯，對你幫助很大？

HBase 2.0 你應該了解的新特性

重構 - 設計API的擴展機制

我的微信智障助手的設計思路