我并不想讨论什么高深的理论先讲一个最实际的应用场景你在做一个周报自动生成工具用户输入任意日期系统要告诉他“这周是2025年第几周”“这周的周一和周日分别是哪天”。听起来简单但真正动手做的时候你会发现“周”的定义五花八门跨年那几天更是重灾区。这篇文章就从“获取输入日期所在的那周”这个小需求切入把周的划分原理、标准库实现、手写算法、跨年边界条件和测试用例一次讲透适合正在写日期处理功能的开发者也适合被各种周数换算搞到头大的同学参考。1. 为什么“同一周”在不同人眼里可能完全不同1.1 一周从周一开始还是周日开始先说一个最基础的认知冲突周的第一天到底是周一还是周日国内很多业务系统习惯把周一当作一周的开始因为“周一上班一周开始”符合职场直觉。但北美地区普遍把周日作为一周的第一天日历上也是周日排在开头。如果你在做一个面向全球用户的工具这个差异不是小事它直接决定你算出来的“本周起始日”是差一天的。除了起始日不同周的归属规则也有分歧。最常见的有两套规则ISO 8601标准一周从周一开始每周年至少包含4天即该周的周四必须落在当年内。北美式规则一周从周日开始1月1日所在的那一周就是第1周不管1月1日落在星期几。这两套规则在绝大多数普通周里没有区别但在跨年那几天会立刻分叉。比如2026年1月1日是周四按照ISO规则这一天属于2025年的最后一周按照北美式规则它属于2026年的第1周。同样是“获取本周”结果差了整整一年。1.2 ISO 8601的核心规则周一加周四归属法ISO 8601之所以成为事实标准是因为它有一套严谨、可计算的归属逻辑。它的核心只有两条每周从周一开始周日结束。某一天属于哪一年的哪一周取决于该周的周四落在哪一年。为什么要看周四因为一周有7天周四恰好是中间偏后的一天。只要这周的周四落在1月1日所在的年份里这周至少有4天属于该年。这个“周四归属法”保证了每一周不会因为年初或年末被截成两半也让每年的第1周一定包含1月4日。举个例子2021年1月1日是周五。ISO规则下这一周的周四2020年12月31日落在2020年所以2021年1月1日属于2020年的第53周。很多人会在这里下意识算错因为直觉上“1月1日都到了怎么还算上一年的周”。1.3 北美式规则与ISO规则的实际差异对比把两套规则放在同一批日期上对照差异一目了然日期ISO 8601归属周一为起始日北美式归属周日为起始日2021-01-01周五2020年第53周2021年第1周2021-01-03周日2020年第53周2021年第1周2021-01-04周一2021年第1周2021年第2周2026-01-01周四2025年第53周2026年第1周2026-01-04周日2026年第1周2026年第2周我一开始做周报工具时直接用了系统自带的周数函数结果运营同事拿着日历跟我说“2021年1月1日怎么显示是2020年”。后来才发现系统默认走的是ISO规则而团队内部习惯用的是北美式。所以做任何日期功能之前先确认业务方要的是哪套规则这是最容易被忽略、又最核心的决策点。2. Python实现直接用标准库而不是手推“偏移量”2.1 isocalendar()返回什么Python的datetime模块自带isocalendar()方法这是最稳妥、最省事的ISO周数获取方式。它返回一个命名元组包含三个字段yearISO年份注意这个年份不一定等于日期所在的公历年份。weekISO周号范围是1到53。weekdayISO星期几周一是1周日是7。代码很简单from datetime import date d date(2021, 1, 1) print(d.isocalendar()) # result: (2020, 53, 5)(2020, 53, 5)表示2021年1月1日属于2020年的第53周且当天是周五。很多人以为isocalendar()的year就是d.year实际不是。这里的年份是“ISO周所属的年份”跨年场景下它可能比公历年份小1年初或大1年末。如果你想同时知道公历年月日就得把两个概念分开不能混用。我之前见过有人直接用d.year拼周数结果跨年那几天全乱了。2.2 根据ISO周数反推本周周一和周日拿到(year, week, weekday)之后“获取输入日期所在的那一周”还差最后一步算出这周的周一和周日具体是哪一天。借助datetime自带的isoformat()参数可以直接构造ISO周的每一天from datetime import date def get_week_start_end(d: date) - tuple[date, date]: iso_year, iso_week, iso_weekday d.isocalendar() # ISO周从周一开始weekday1表示周一 monday date.fromisocalendar(iso_year, iso_week, 1) sunday date.fromisocalendar(iso_year, iso_week, 7) return monday, sunday d date(2021, 1, 1) monday, sunday get_week_start_end(d) print(monday, sunday) # 2020-12-28 2021-01-03date.fromisocalendar(year, week, weekday)是Python 3.8引入的方法专门用于“ISO周号转日期”。很多教程教你用timedelta手动推算但标准库既然提供了现成的逆运算就没必要自己造轮子。如果你用的是Python 3.8以下版本可以改用datetime.strptimefrom datetime import datetime def from_isoweek(year: int, week: int, weekday: int) - date: return datetime.strptime(f{year}-W{week:02d}-{weekday}, %G-W%V-%u).date()%G、%V、%u分别是ISO年份、ISO周号、ISO星期几的格式化指令这个思路可以作为旧版环境的兼容方案。2.3 为什么不要用timedelta手动从“1月1日”推周数很多初学者会走这条路先算当年的1月1日是星期几再算输入日期距离1月1日的天数除以7得到周数。这个思路看似合理实际到处是坑。首先1月1日可能是上一年的第52周或者第53周直接用它做偏移基准你的“第1周”就比ISO第1周少了一截。其次不同年份1月1日的星期不同按天数除以7会得到3种不同结果你还得针对每种情况分别写补偿逻辑代码复杂度指数上升。举个反例from datetime import date, timedelta d date(2021, 1, 5) jan1 date(2021, 1, 1) days (d - jan1).days # 4 week days // 7 1 # 1看起来是1但ISO规则下2021年1月5日属于2021年第1周这不就巧了别急再试1月1日2021年1月1日按这个算法是第1周实际是2020年第53周。2022年1月1日按这个算法是第1周实际是2021年第52周。也就是说你写出来的工具会在每年年初随机出错而恰好年初又是用户最在意周数的时候。这种代码我才写过一次就不想再写了“能跑”和“正确”之间差的就是跨年那几天的处理。2.4 返回格式的坑datetime.date与strftime的差异用strftime也可以拿周号d date(2021, 1, 1) print(d.strftime(%G-W%V-%u)) # 2020-W53-5这里的%G是ISO年份%V是ISO周号%u是ISO星期几1-7。注意千万别写成%Y-%W-%w。%Y是公历年份%W是“从周一开始计数的周数”但第1周以1月1日为基准%w是周日为0的星期几三者拼在一起在跨年时会得出完全不可信的结果。print(date(2021, 1, 1).strftime(%Y-W%W-%w)) # 2021-W00-5W00周数是0这就是春节日历上永远对不上的根源之一。%W允许范围是00到53它的第1周从“第一个周一”开始算跟ISO第1周不是一回事。所以格式化输出周数时请务必锁定%G-W%V组合。3. 跨年边界一整年最容易被“第53周”骗到的地方3.1 第53周是怎么出现的以及哪一年会出现ISO规则下大多数年份只有52周因为365天除以7是52周余1天366天则是52周余2天。但每个ISO年可能出现53周条件很具体平年1月1日是周四该年有53周。闰年1月1日是周三或周四该年有53周。这个条件的背后是“该年包含至少4天的周才算当年周”。1月1日是周四时它的ISO周至少有4天落在当年所以这周被计为该年的第1周最后会多出来一个第53周。日常开发中第53周最容易和“最后一周的周日是12月30日还是1月3日”混在一起。比如2020年是ISO的53周年份2020年12月31日是周四它属于2020年第53周这一周的周日是2021年1月3日。你的代码如果按“12月31日的周日”去推就会推成2021年1月10日整段逻辑全部错位。3.2 1月1日在不同星期时归属完全不同的年这是跨年边界的精华。把1月1日的星期值和ISO归属做个完整对应1月1日星期该日属于哪一ISO年该日属于哪一ISO周周一当年第1周周二当年第1周周三当年若为闰年则当年第1周平年则仍为当年第1周第1周周四当年第1周周五上一年的第53周上一年的第53周周六上一年的第52周上一年的第52周周日上一年的第52周上一年的第52周注意周五是最特殊的它所在周的周四落在上一年的12月31日按“周四归属法”整个周都算上一年的第53周。这也是开发者最容易错的地方因为直觉上“周五明明是本周最后一天”。我处理2025年1月1日时专门验证过2025年1月1日是周三ISO规则下它属于2025年第1周。再回看2021年1月1日是周五直接掉到2020年第53周。两年只差一个星期几归属年份就完全不同。3.3 边界测试用例建议直接抄走我做日期功能时会把这些日期直接写进单元测试import unittest from datetime import date class TestISOWeek(unittest.TestCase): def test_boundary_cases(self): cases [ # 输入日期, 期望ISO年份, 期望ISO周号, 期望星期几 (date(2021, 1, 1), 2020, 53, 5), (date(2021, 1, 3), 2020, 53, 7), (date(2021, 1, 4), 2021, 1, 1), (date(2021, 12, 31), 2021, 52, 5), (date(2024, 12, 30), 2025, 1, 1), (date(2026, 1, 1), 2025, 53, 4), ] for d, exp_year, exp_week, exp_wd in cases: iso d.isocalendar() self.assertEqual((iso.year, iso.week, iso.weekday), (exp_year, exp_week, exp_wd))这里最难想到的是2024-12-30——2024年12月30日是周一但它属于2025年的第1周因为2025年1月1日是周三这一周有5天落在2025年。如果只看日期你根本想不到它已经“跨年”了。4. JavaScript实现没有isocalendar时的手写方案4.1 为什么不能直接用getDay()推算JavaScript的Date.prototype.getDay()返回的是0到6其中0表示周日。这个设计害人不浅因为它跟ISO规则里“周一1”的编号完全对不上。很多手写实现会这样写function getWeekOfYear(date) { const start new Date(date.getFullYear(), 0, 1); const diff (date - start (start.getTimezoneOffset() - date.getTimezoneOffset()) * 60000) / 86400000; return Math.ceil((diff start.getDay() 1) / 7); }这个算法在非跨年场景下能用但闰年、跨年和不同时区下会存在不少边缘误差。我自己踩过最无语的一坑同一个日期在东八区显示第1周在UTC环境跑出来是第53周因为getTimezoneOffset的差在临界日期上造成了偏移。如果只想在JavaScript里拿ISO周号手写一个纯数学版最可靠。不用getTimezoneOffset也不依赖本地时区完全基于UTC计算逻辑简单也方便测试。4.2 手写ISO周号函数function getISOWeeks(date) { // 将输入日期转换为UTC避免本地时区干扰 const target new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())); const dayOfWeek target.getUTCDay() || 7; // 转为ISO星期几周日7周一1 target.setUTCDate(target.getUTCDate() 4 - dayOfWeek); // 移动到本周周四 const yearStart new Date(Date.UTC(target.getUTCFullYear(), 0, 1)); const weekNumber Math.ceil((((target - yearStart) / 86400000) 1) / 7); return { year: target.getUTCFullYear(), week: weekNumber }; } console.log(getISOWeeks(new Date(2021, 0, 1))); // { year: 2020, week: 53 } console.log(getISOWeeks(new Date(2026, 0, 1))); // { year: 2025, week: 53 }这段代码的思路是先把日期挪到它所在周的周四再数这个周四距离当年1月1日是第几周。挪到周四这一步是灵魂因为它把一个“哪天算哪周”的语义转换成了“这个周四落在哪一年”完美规避了跨年的所有歧义。你不需要再记周五归上一年、周日归下一年这类规则算法替你处理了。4.3 只取日期的必要性JavaScript的new Date(2021, 0, 1)在本地时区是2021年1月1日0点。如果你直接拿这个时间戳参与日期运算在UTC8之外的时区可能出现跨时区回退导致日期变成2020年12月31日。所以我的习惯是先把它转成UTC再算或者先从年月日构造一个UTC日期。上文的实现里第一步就是Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())把时分秒全部清零并统一到UTC坐标系避免时区偏移篡改日期。这样无论用户在中国、美国还是欧洲同一输入日期得到的周号完全一致。4.4 再补一个“周一到周日”的范围计算拿到ISO年份和ISO周号后JavaScript同样能反推本周起止function getWeekRange(year, week) { // 找到该年1月4日它一定在ISO第1周内 const jan4 new Date(Date.UTC(year, 0, 4)); const jan4Day jan4.getUTCDay() || 7; const mondayOfWeek1 new Date(jan4); mondayOfWeek1.setUTCDate(jan4.getUTCDate() - (jan4Day - 1)); const monday new Date(mondayOfWeek1); monday.setUTCDate(mondayOfWeek1.getUTCDate() (week - 1) * 7); const sunday new Date(monday); sunday.setUTCDate(monday.getUTCDate() 6); return { monday, sunday }; } console.log(getWeekRange(2020, 53)); // 2020-12-28 ~ 2021-01-03为什么找1月4日而不是1月1日因为ISO第1周一定包含1月4日这是一条铁律。以1月4日为锚点反推第1周的周一再往后加(week - 1) * 7天就得到任意ISO周的起始日。这个锚点选对了整个计算几乎不可能出错。5. 实战经验日期工具里最容易忽略的细节5.1 永远先确认业务方要的是“自然周”还是“ISO周”我见过不少团队开发前没对齐这个定义上线后被用户骂“你们系统怎么把周六算到下周去了”。先问一句“周一是一周的开始吗”再决定用哪套规则比事后改逻辑省一百倍力气。如果业务方说“我们用自然周周一为起始日”那基本等同于ISO规则如果业务方说“周日为起始日”那就是北美式。两种规则实现的代码几乎完全不一样不能在同一个函数里靠参数切换糊弄过去因为跨年周的年份归属也跟着变了。5.2 只保留日期别让时分秒掺和进来日期计算最怕的是“带时间的日期对象”。输入2024-06-15 23:59:59和输入2024-06-15 00:00:00理论上应该算出同一个周号但因为时区、夏令时和getTimezoneOffset的存在结果可能不同。所以在进入周计算之前统一做一步“截断”只保留年月日时分秒全部归零。Python里用date对象而不是datetime对象JavaScript里用Date.UTC(year, month, day)。这一步做好后面所有时间运算都不会出现“差一天”的诡异偏差。5.3 测试用例要覆盖“周五的1月1日”和“闰年的1月1日周三”我整理了一份覆盖关键边界的日期清单不管用什么语言实现直接拿来当基准测试日期期望ISO年期望ISO周2019-12-30202012020-12-312020532021-01-012020532024-12-30202512024-12-31202512025-01-01202512026-01-01202553这里每一行都是真实踩过或者差点踩过的坑。尤其是2019-12-30和2024-12-30这两个日期都在12月底但已经属于下一年了肉眼非常具有迷惑性。5.4 输出周数时保留“上年/今年”的信息在实际业务里只返回一个“第53周”是不够的必须同时返回ISO年份。因为“2020年的第53周”和“2021年的第53周”是两回事哪怕日期只差几天。我在数据结构里习惯直接返回{ isoYear: 2020, isoWeek: 53 }宁可多一个字段也不让用户自己去猜。如果是要生成报表标题建议直接拼成2020-W53这种带年份前缀的格式避免和别人口头沟通时出现“这周五是第几周”的歧义。5.5 如果只记一句话周四归属法是万能的钥匙不管是手写算法还是调标准库绕来绕去都离不开“看周四落在哪一年”这条规则。只要理解了这点跨年周的所有特殊情况都能自己推导出来而不是靠背表格。我个人做了这么多日期功能后的体会是日期处理没有任何魔法核心就是边界情况全覆盖。每次拿到新的日期范围需求先把跨年、闰年、周五、周日这些刁钻日期写进测试用例越早暴露问题越好。等这些用例全通过了这个“获取输入日期所在的那周”的小工具才能真正交付到用户手里而不被骂。